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

[michael.vancanneyt at wisa.be]

On Wed, 31 Aug 2011, Hans-Peter Diettrich wrote:

> michael.vancanneyt at wisa.be schrieb:
>
>> In each case, the opposite is already so. The documentation of an
>> enumerated-typed property will normally link to the enumerated type.
>
> This doesn't make sense, because the meaning of an enum member can vary, 
> depending on the context (class with property). Useful documentation should 
> explain all available options together, and should not require to click 
> through all related declarations, in order to find out what options exist.

Yes. It does so in FPC.

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

So no need to 'click through'. All is together in 1 page.

Michael.