On Sat, 28 Jan 2012, Hans-Peter Diettrich wrote:
Michael Van Canneyt schrieb:
On Sat, 28 Jan 2012, Hans-Peter Diettrich wrote:
[email protected] schrieb:
On Fri, 27 Jan 2012, Hans-Peter Diettrich wrote:
should first document dependent units. It currently does not know how
to do this by itself.
Again, what are you talking about? FPDoc doesn't require a special order
of input files, neither source nor documentation files :-)
It does, see the explanation of Marco.
I still don't understand this requirement, and how documentation writers
should establish the correct order :-(
Simple.
The same order as the compiler uses: it is 100% determined by the uses
clause.
How is that related to documentation and the order of input files?
If you refer to a type in a unit, then the parsing engine tries to resolve the
type.
If it finds the type, then it creates a straight reference to this type.
if it does not, it creates a TPasUnresolvedTypeRef instance.
From this you can see that the order in which the parsing engine parses units
matters:
if the order is correct, then you will not have any TPasUnresolvedTypeRef instances,
because the engine will be able to find all types. If the order is not correct, then
there will be lots of TPasUnresolvedTypeRef instances.
Now, when the HTML engine constructs its pages, there are links that it must resolve by
itself (parent classes, type references in all kinds of places etc). If a
TPasUnresolvedTypeRef is encountered, it will not know how to make the reference.
It can (and does) try to guess, but often the guess fails.
When every module can have a different order of the used units, how should
this be reflected in an fpdoc commandline or project?
It's a simple tree.
Why is this so surprising ? How do you think the lazarus codetools manage
this ? Exactly the same way. It's not black magic, but very deterministic.
Please don't blame the users, and don't remove useful functionality like
--input-dir, when the bug resides in the documentation generator, and cannot
be cured by ordering the input files :-(
I am not blaming anyone for anything.
But if I tell you that order matters, please be so kind to assume that I know
what I'm talking about: I spent far more time on fpdoc and all related units
than anyone else on these lists.
As for the presence of --input-dir, we'll see. I understand why you want it.
God knows I spent enough time mailing about it.
Michael.
_______________________________________________
fpc-devel maillist - [email protected]
http://lists.freepascal.org/mailman/listinfo/fpc-devel
