[fpc-devel] FPDoc improvements

[Michael Van Canneyt]

On Sat, 28 Jan 2012, Hans-Peter Diettrich wrote:

> Michael Van Canneyt schrieb:
>> On Sat, 28 Jan 2012, Hans-Peter Diettrich wrote:
>> 
>>> michael.vancanneyt at wisa.be 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.