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.
Show quoted text 5 lines
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.
