[fpc-devel] FPDoc improvements

[Michael Van Canneyt]

On Sun, 29 Jan 2012, Hans-Peter Diettrich wrote:

> Marco van de Voort schrieb:
>> In our previous episode, Michael Van Canneyt said:
>>> The question you asked:
>>> 
>>> "How is that related to documentation and the order of input files?"
>> 
>> I've the feeling that Dodi assumes all references are fully qualified and
>> not just the inter-package ones?
>
> No. I'm familiar with parsers in theory and practice, but not with the 
> implementation details of the pparser and fpdoc.
>
> I know about the use of unqualified names (and links) in source code, and 
> that these must be looked up in an declaration tree. Then I only can assume 
> that such a tree is built from the currently parsed source module, but 
> references to other unites (in "uses") are not implemented properly. As you 
> already pointed out, the search order depends on the order of the units in 
> the uses clause, while the parser currently seems to use the order of fpdoc 
> input files and imports? These (technical) aspects never has been described 
> in all the answers, instead everybody proceeded immediately to explain 
> solutions for never mentioned implementation flaws :-(

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

* 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.
- We parse recursively. But only if the unit is in the input list, otherwise you end up parsing all of the FPC
   sources.

Michael.