[Lazarus] Adding Notes in FPDoc

[Hans-Peter Diettrich]

Graeme Geldenhuys schrieb:
> On 11 February 2012 12:23, 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.

Not me ;-)

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

A better help system should allow to show or hide details based on more 
criteria. In Delphi and MS (.NET...) help it would be helpful to show 
the texts associated with a specific language. In FPC/Lazarus help the 
platform or widgetset details could be shown or hidden. In all cases the 
use case could be honored, like:
- user needing instructions for calling a method in code
- user having (known?) problems with a method
- component writer wants to override a method
- expert wants to fix or extend a method

All that can not be achieved with only a level of verbosity.


Please note that I don't ask for such a feature in FPDoc (right now). I 
only mention it in case somebody wants to implement a similar feature. 
An implementation could extend the <notes> tag with arbitrary 
conditions, interpreted in generating the docs, or later in a viewer. 
Kind of conditional compilation, guided e.g. by -dExpert etc. on the 
fpdoc (or viewer) commandline.

DoDi