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)