[fpc-devel] FPDoc improvements

[Hans-Peter Diettrich]

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?

DoDi