fpdoc extension: embed topic [Re: [fpc-devel] FPDoc sources]

[Hans-Peter Diettrich]

michael.vancanneyt at wisa.be schrieb:

> For example
> 
> http://www.freepascal.org/docs-html/rtl/classes/tfilestream.create.html
> 
> In fact a bad example, because the option is not an enumerated type but
> simple constants.

Nonetheless this one comes close to my expectations.

It e.g. explains why the method name should be mentioned in the short 
description of the constants, so that the user can know (and jump to) 
the procedure or method, in which the contant is used (exclusively).

With the downside that this link occurs again in the description of the 
method itself, and may lead to a different (base) class, when reached 
from an overridden method in a derived class. Without above insight I 
had put a definition list into the method description, describing the 
constants.


> So let us look at
> 
> http://www.freepascal.org/docs-html/rtl/classes/talignment.html
> 
> The TAlignment declaration contains a description for all options. 
> Generated
> automatically by fpdoc, because it knows from the sources that TAlignment
> is an enumerated, and therefore it automatically prints a short description
> for all enumerated elements in the definition.

Are such fpdoc automatisms documented somewhere[1]?

Every documentation writer should know what is done behind the scene, so 
that the entries can be structured accordingly. (see above)

I already asked for samples or templates, which can be used to describe 
elements of the same type. Above links look good for that purpose, for 
both true enums (TAlignment) and related constants (TFileStream).

A counterexample is TDuplicates
http://www.freepascal.org/docs-html/rtl/classes/tduplicates.html
for which it's near impossible to find any details :-(
Obviously fpdoc here is fooled by the "TDuplicates = Types.TDuplicates" 
declaration, so that it can not give the detailed description for 
Classes.TDuplicates, and furthermore short descriptions for the enum 
elements seem to be missing in the xml files.

Can you suggest a solution for these problems, so that 
TStringList.Duplicates will be documented in a useful way?

As you can see in 
http://www.freepascal.org/docs-html/rtl/classes/tstringlist.duplicates.html
the descriptions had to be *copied*, in order to make them visible 
there, and all links to the TDuplicates type require to follow further 
links.


BTW, it would be very nice to have the class members sorted 
alphabetically, regardless of their type or arrangement in the class 
declaration. It's very hard to find Duplicates in the TStringList 
description :-(


[1] I happened to find some hints in fpdoc "5.1 HTML output" 
description. More and better structured descriptions can be found for 
"5.2 Latex output". More information should be available, for e.g. the 
handling of overridden/inherited methods and properties. This may be 
hidden somewhere else, but IMO should be documented all together in an 
"How to" fpdoc users guide. When I want to create such an users guide, 
can you suggest an good place/title in the wiki?

DoDi