[fpc-devel] FPDoc improvements

[Hans-Peter Diettrich]

Michael Van Canneyt schrieb:

> Well, you have the sources, you can look up the actual implementation.
> Then you would see that:

Please don't confuse syntax and semantics. Reading source code reveals 
only *what* is done, but not *why* it's done, and what are the consequences.

> * The fpdoc engine keeps a list of units to parse.
>   It keeps all symbols from all units it parses in a large tree.
> * The passrc parser parses 1 unit at a time. * If the parser encounters 
> a uses clause, it simply notes the dependency; no more, no less.
>   In particular: it does not start parsing the unit in the uses clause 
> if it was not yet parsed.
> * If the parser needs to look up a symbol, it searches for symbols in 
> the fpdoc list, in all the
>   units for which dependencies were noted.
> 
>> From this it follows that the order of parsing the units matters: 
> the symbol must be there in order for the parser to find it.
> 
> To avoid having to specify the correct order, there are now 2 possible 
> solutions:
> - We do 2 passes.
>   One to establish parsing order (it can stop after the uses clause), 
> the second to actually parse.

Lazy variation:
Stop when a used unit was not already parsed, postpone the blocked unit 
in the parse list, and move the used unit in front of it - kind of 
bubble sort.

> - We parse recursively. But only if the unit is in the input list, 
> otherwise you end up parsing all of the FPC
>   sources.

That's how FPC works, except for the input list.


Thanks for the enlightenment, now I also see the impact of the input 
list order :-)

DoDi