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.

You can add several files as parameters, like that, every structure and interface in the files is global for this process and must only be declared / defined once! But now all structures / interfaces in every file will be linked with its source file.

In addition, you can specify all these parameters in your source code directly. Just write a target comment with the parameter:
;** /notstart temp__
;** /onlydll