[fpc-pascal] *** GMX Spamverdacht *** Re: SizeInt documentation

[leledumbo]

> Then something is wrong with how the documentation is "generated"
(shouldn't it be written by a human?).

In these automatic documentation generator days? I don't think so.

> A documenation of a type that has different meanings on different
> platforms should tell about this. 
> That's what a documentation is for!

Well, the user guide, programmer's reference or basically everything other
than the API documentation mentions whenever something is platform specific.
And they're hand written.

> How should I know that these documentations are for *nix only?

*nix units are not available on non-nix platforms, it's that simple.

> That is totally missleading and makes the "documentation" useless.
> It does not inform about all side effects which IMO is the purpose
> of a documentation. Otherwise I can also guess (and try).
> I would expect that the "source" part is manually written in the same 
> way as the "description" part.

Going back to everything manual is NOT a solution (How many places must be
modified when an API changes? How do you ensure the documentation and source
be consistent?), find something else possible and feasible. If you want to
hack fpdoc parser to include all possible definitions, by all means go ahead
and send the patches. Do something like what doxygen does:
http://www.stack.nl/~dimitri/doxygen/manual/preprocessing.html where the
directive processing is controllable by a switch. I have no idea how hard is
that, AFAIK it uses fcl-passrc which is a generic Object Pascal (as
understood by FPC) parser. That could be your starting point.

FYI, you can generate the documentations yourself, so it will be specific to
your platform.



--
View this message in context: http://free-pascal-general.1045716.n5.nabble.com/SizeInt-documentation-tp5721877p5721889.html
Sent from the Free Pascal - General mailing list archive at Nabble.com.