[fpc-devel] FPDoc improvements
DrDiettrich1 at aol.com
Sat Jan 28 11:50:05 CET 2012
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
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
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?
More information about the fpc-devel