jaPBdoc

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.

Special Comments

There are two kinds of special comments:

;**

This comment is the target comment. It defines to what the following information belongs to. You can put a : after the target. Then the text behind will be added as a documentation line to the target. A target looks like this:

[type] [name][.element]
So a full target comment looks like this:
;** [type] [name][.element][: documentation]

;*

This comment holds information that belongs to the last target. Each such comment will be added without a line feed to the previous one. To add a line feed, just put a _ as the last char of such a comment.
In the overview-tables, only the first line or the first phrase will be shown.

File 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

Function/Macro 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

Structures, Interfaces, Constants and Global Variables Documentation

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.

Program Parameters

You can add simple filters (only one at once):

/notstart

The next parameter is a string. No target starting with this string will be documented.

/onlystart

The next parameter is a string. Only targets starting with this string will be documented.

/onlydll

Only ProcedureDLL and ProcedureCDLL will be shown as functions.

/nodlltable

DLL functions don't get an extra table.

/nofunctions

No functions will be shown

/noglobals

No global vars will be shown

/nostructs

No structures or interfaces will be shown.

/noconstants

No constants will be shown.