[Lazarus] Adding Notes in FPDoc

[Hans-Peter Diettrich]

Michael Van Canneyt schrieb:

> Seeing the discussions about annotating the documentation created by 
> FPDoc, I added support for notes.
> (revision 20304)

Thanks :-)

> In short:
> 
> At the level of the <module>, <topic> and <element> tags, you can now 
> include a <notes> tag.
> 
> Within the <notes> tag, you can include one or more <note> tags.

Why so complicated? Can you give a *reasonable* example of the intended 
usage of this feature?

> They are typeset as an unordered list, which means that it can basically 
> contain the same things as a <li> element.
> (so no tables, code blocks and what not).
> 
> By default, the <notes> tag is ignored.
> 
> Only if you give fpdoc the --emit-notes option, then the notes will be 
> included in the output.
> (at least in HTML and all linear output).

It looks to me as if you only implemented only half of a possibly much 
more powerful feature. Provided that your intention is about 
*conditional* parts, which are formatted for inclusion into the final 
docs, I'm missing more detailed condition handling. Then it would be 
possible to e.g. provide documention specific to a platform or 
widgetset, wherever different implementations or behaviour suggest such 
separate documentation.

Apart from that, author/editor notes deserve no special structure or 
formatting, and should be easier to insert (what about LazDE?).

What about a less structured solution, e.g.
   <notes XYZ deserves a clarification!/>
for an alternative use of the just introduced tag?
(exact syntax to be specified)

In contrast to:
   <notes><note>XYZ deserves a clarification.</note></notes>
or
<notes>
   <note subject="win32">On Win32 ...</note>
   <note subject="linux">On Linux ...</note>
</notes>


> The fpdoc XML project file also supports the emit-notes option.
> 
> I have documented all this it in the official fpdoc reference guide. 
> (rev. 890)

Available how/where? 
<http://lazarus-ccr.sourceforge.net/fpcdoc/fpdoc/fpdoc.html> still is 
from 2008.

Okay, found it - but it should be accessible easier, without rebuilding 
all the FPC docs. Above questions/annotations still apply, examples welcome.

DoDi