| GBH3(1) | User Commands | GBH3(1) |
gbh3 - GAMBAS documentation generator for C/C++ components
gbh3 [options] [<sources>]
gbh3 is a tool to generate GAMBAS online documentation from documentation strings embedded in C or C++ source code of native GAMBAS components.
Components written in Gambas can already be documented in-code. This documentation is then stored inside their .info files.
If <sources> contains directories, they are searched recursively for '*.c' and '*.cpp' files. If <sources> is not specified, the current directory is searched.
The extracted help is printed on the standard output, unless the '-c' option is specified.
The expected syntax is demonstrated at the examples. The difference between both notations is that the first must immediately precede a BEGIN_{PROPERTY,METHOD,METHOD_VOID) line that defines the symbol which the documentation refers to. The second syntax documents the indicated symbol -- no matter where the comment is.
This is intended to document GB_CONSTANTs or GB_PROPERTY_SELFs which don't have a BEGIN_* line. Nevertheless, it can be used for any other symbol. NEVER mix both syntaxes on a single symbol.
The ClassName_MethodName part I call "(implementation) function name". The particular function naming convention shown is not mandatory. The scripts take the function name and look up the corresponding symbol in your GB_DESC[].
The regular expressions used to filter these comments are somewhat strict. You have to pass the spaces exactly as indicated in the line where your comment text starts, i.e. <space>*<space>text. Also note that Class and Symbol in the second syntax are case sensitive!
Don't reuse method and property implementations (except for synonyms).
As the implementation function name is searched in the GB_DESC[]s in your source file, you may not put the same function into different classes -- or the parser may get confused.
Also, keep the GB_DESC[] in the same source file as the help comment.
The first match for a function name lookup in a GB_DESC[] is taken as the "primary" implementation of that symbol. That means the help comment will be attached to that symbol. All other symbols which call the same function are considered synonyms and are *automatically* documented with the default sentence: "This is a synonym for <primary-symbol>". DO NOT document them separately using a syntax-2 help block!
You may write a Gambas documentation comment like
/**G
* Here goes the documentation.
**/
BEGIN_METHOD_VOID(ClassName_MethodName)
/* ... */
END_METHOD
or alternatively
/**G Class Symbol
* Documenting Class.Symbol
**/
Instead of the **/ at the end, you may also write */. Cool, huh? The second syntax can also be used to document the class per se:
/**G Class
* Class documentation here
**/
Have a look at the gb.openssl and gb.data components that are partially documented that way. Digest.Hash() and Digest._call() in gb.openssl show how to deal with synonyms. The entry for Hash precedes the entry for _call, thus Hash is the primary symbol and _call a synonym.
Updated source code and most documentation about Gambas can be found at http://gambas.sf.net.
Bugs are filed at http://gambaswiki.org/bugtracker.
gambas3(1), gba3(1), gbc3(1), gbi3(1), gbr3(1), gbs3(1), gbw3(1), gbx3(1)
| 2018-10-28 | Debian |