Hi,

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

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.

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

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)

As a side note:
The official FPC documentation will not contain notes in the output. I consider them for private use only, so it is useless to submit notes. But I can understand other people want such a feature, therefor I added it to fpdoc.

Michael.

Michael Van Canneyt wrote

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

Thank you Michael, this should definitely come in handy for some people.

I also investigated this functionality further with INF and DocView. The INF specification has support for a "hide" function. These HIDE tags takes into account an environment variable in the OS, which tells the INF viewer if that content should be displayed or not. INF takes it one step further and even allows you to specify various "access levels" separated by a + sign (eg: set IPF_KEYS=LEVEL1+LEVEL2) to have even more fine-grained control over which notes are displayed or not.

So based on this, fpdoc notes could be displayed or hidden using a single INF file - simply by toggling the value of the IPF_KEYS environment variable.

I'll pull the latest fpdoc code and experiment with this functionality a bit more.

Graeme Geldenhuys wrote

So based on this, fpdoc notes could be displayed or hidden using a single INF file - simply by toggling the value of the IPF_KEYS environment variable.

IMHO, multiple verbosity levels are a great idea and even more useful than just "Notes" that can be hidden. But I would vote for letting the user decide at any point in time to switch the verbosity level in the help viewer itself rather than use a static environment variable.

-Michael

Michael Schnell wrote

just "Notes" that can be hidden. But I would vote for letting the user decide at any point in time to switch the verbosity level in the help viewer itself rather than use a static environment variable.

That's already on my DocView todo list. :-)