NAME

       gbh3 - GAMBAS documentation generator for C/C++ components

SYNOPSIS

       gbh3 [options] [<sources>]

DESCRIPTION

       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!

OPTIONS

       -r, --root <root>
              the GAMBAS installation directory

       -c, --component <component>
              generate help directly in a component '*.help' file

       -v, --verbose
              Enables verbose output.

       -V, --version
              Displays the program's version.

       -L, --license
              Displays the program's license.

       -h, --help
              Displays help information.

EXAMPLES

       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.

NOTES

       Updated source code and most documentation about Gambas can be found at http://gambas.sf.net.

BUGS

       Bugs are filed at http://gambaswiki.org/bugtracker.

SEE ALSO

       gambas3(1), gba3(1), gbc3(1), gbi3(1), gbr3(1), gbs3(1), gbw3(1), gbx3(1)

Debian                                             2018-10-28                                            GBH3(1)