jaPBdoc is a tool that scans your source file for all procedures, constants, macros, structures, interfaces, include files and global variables. You can add information to each of these with special comments right in the source file. jaPBdoc then creates a HTML file with this documentation.
There are two kinds of special comments:
[type] [name][.element]
;** [type] [name][.element][: documentation]
To add a documentation for the whole file, put an empty target to the target
comment: ;**
Now every ;* comment adds its text to the file documentation
For macros and functions you just have to put the name as a target:
;** funcname
To document its parameters, expand the target:
;** funcname.paramname
You can even use a shorter version after you once defined the function:
;** .paramname
Of course all these target comments also work in the short form:
;** .paramname: Info
For structures and interfaces, it is the same like for functions, except
you have to specify a type for the target:
;** type structname[.element]
For structures, the type is 's', for interfaces 'i', for constants it is
optional 'c' and for global variables 'g'.
Every combination in the target comment should work:
;** s struc.field1: docu
;** i interfacename: docu
;** .method: docu
etc.
For elements of structures and interfaces as well as for constants, global
variables and functions there is yet another easy way to add a
one-line-documentation. Just write a ;*-comment behind the element (in a
structure/interface block) or the constant/procedure-header/global declaration:
#Const ;* info
Structure TEST
d.l ;* info
EndStructure
global a.l, b.l ;* docu only for b!
procedure test() ;* docu for test()
endprocedure
All this one-liners won't change the target (set by a ;**-comment), but also
won't add anything to it, they are separate. You mustn't assume that the target
changed and now every ;*-comment will add to this target now.
Another important thing is, that you can only document everything once! If you
try to document it twice (or more), the description won't be added to the
existing, but will overwrite it! So i. c. this will not work:
#Const ;* info
;* c #Const: another one
The same for all other things, you can't change the target and then change back.
You will get a warning on the command line.
You can add simple filters (only one at once):
;** /notstart temp__
;** /onlydll