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)