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
--
_______________________________________________
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
