[fpc-devel] FPDoc improvements

[Hans-Peter Diettrich]

Marco van de Voort schrieb:
> In our previous episode, Mattias Gaertner said:
> 
>>> [...]
>>> For the --input-dir there is an extra reason: the order of files is important.
>>> Just like in the compiler, which must compile dependent units first, fpdoc
>>> should first document dependent units. It currently does not know how to do 
>>> this by itself.
>> Contrary to the compiler the fpdoc files can refer freely to each other.
>> Is the above "should first document dependent units" your preference
>> or is there really a reason? 
>> What if I need an alphabetical or logical order (e.g. the most
>> important at top)?
> 
> The parsing order and the order in the overview pages should then be
> decoupled (e.g. by a sorting event that is configurable)
> 
> The parsing order is mandatory even. I still have to research the
> consequences for latex. The latex backend currently doesn't seem to suffer from
> order problems which is probably means it is vulnerable to duplicate
> identifiers.

Linear documents IMO should follow their own rules, which make the docs 
readable. A simple concatenation of element descriptions is a poor man's 
solution, far away from e.g. the Delphi(7) PDFs. I'd suggest a skeleton, 
containing the document structure and verbose parts, and include 
instructions for the XML elements, overviews and tables, created e.g. 
for class members.

> The html backend however isn't free from this, but has the limitation that
> it only suffers from duplicate identifiers wrt already parsed units and .xct
> modules.

Isn't this a matter of properly linking identifiers, declarations and 
descriptions to each other? What detailed information does the PParser 
need about identifiers declared somewhere else?

DoDi