[fpc-devel] FPDoc improvements
Michael Van Canneyt
michael at freepascal.org
Sun Jan 29 10:38:06 CET 2012
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
More information about the fpc-devel