[fpc-devel] FPDoc improvements
DrDiettrich1 at aol.com
Sat Jan 28 12:52:43 CET 2012
Marco van de Voort schrieb:
> In our previous episode, Michael Van Canneyt said:
>> Meanwhile I have a simple example using 2 units floating around somewhere.
>> It took me lots of time to find it, but now I know where the cause is.
>> Solving it is another matter entirely.
> I've been thinking about it, and following the compilers way of working is
> the only solution.
> If you want to resolve identifiers like a compiler, you have to build scopes
> like a compiler, and do that in the right order.
What's wrong with the current #package.unit.identifier... qualification?
[Apart from the Delphi/.NET aberration of dotted unit names, which
should be avoided in FPC :-]
> Otherwise funny things will happen with duplicate identifiers.
Is this a problem of the implementation parser, or does it also apply to
the interface sections?
Until now I only found problems with overloaded proedures or methods,
which are documented in only one element - nasty but liveable.
Quite a different problem are e.g. platform specific identifiers, for
which the XML files have no special provisions - the same descriptions
are used for every combination of --ostarget and --cputarget values.
Also liveable when the docs mention all eventual essential differences,
and fpdoc always ignores the descriptions of elements without
declarations. But it becomes very nasty when the fpdoc commandlines
contain hard-coded platform-specific include directories, because then
the user will not see help on identifiers of his actual platform :-(
In such cases I also can understand that the parser is fooled by search
pathes for multiple platforms at the same time. Is this problem
addressed (and cured?) by the macro expansion in mkfpdocproj?
More information about the fpc-devel