[fpc-devel] FPDoc improvements

[Hans-Peter Diettrich]

Michael Van Canneyt schrieb:
> On Sat, 28 Jan 2012, Hans-Peter Diettrich wrote:

>>>> 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.

What's the question for this answer? ;-)

>> 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.

IMO we're discussing the third case, when multiple declarations might 
apply. Then the parser has to search the units in their order within the 
uses clause, which is unrelated to the order of input files.

> 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.

Why not try to resolve that reference later, e.g. after construction of 
the content table?


>> 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.

So what? IMO you didn't understand the problem :-(

>>> 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.

Well, maybe you don't see the wood for trees any more? ;-)

> 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.

Perhaps it helps to look closer at the questions, before you give 
answers to questions never asked?

DoDi