| fb-doc 0.2 documentation tool for FreeBasic

- Main Page
- Tutorial
- Data Structures
- Files

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Examples

Here're some examples for the features of fb-doc (using gtk-doc or Doxygen back-end).

# Comments (in general)

Note
  In these examples the ends of the FreeBasic multi line comments are fakes, because the straight single quote mark cannot be used in the source. Instead an acute accent is used. Correct them when you intend to copy / paste the code.

A line end comment in the FB source like

'* a line end comment

gets emitted as

//! a line end comment

Direct export comments in FB source (each are line end comments) like

'&// a line end comment in C syntax
'&/*
'&Some
'&lines of
'&C comment
'&*/

get emitted as

// a line end comment in C syntax
/*
Some
lines of
C comment
*/

And a multi line comment in FB source like

/'*
Some
lines of
comment `/

gets emitted as

/**
Some
lines of
comment */

or — when option –asterix is set — as

    /**
    * Some
    * lines of
    * comment */

Normal FreeBasic comments (without magic character) wont be emitted. (They're only visible in the FB source, The intermediate format contains empty line in that case.)

' a line end comment
/'
A block
of
comment
`/

# Variable Declaration

A varible declaration in a FreeBasic source code line like

DIM VarName AS ZSTRING PTR

gets in the intermediate (C-like) format

ZSTRING_PTR VarName;

The FB type ZSTRING PTR consists of two words. The C scanner can not handle it directly. That's why fb-doc mangels the words in to one word, separeted by an underscore. Now the lexical scanner of the C tool-chain interprets the single word ZSTRING_PTR as a user defined type (or macro) and generates documentation like

    ZSTRING_PTR VarName

See Type Mangling for more examples.

In this syntax the FB user can identify the type as an FB declaration and easily understand the documentation. The only difference is that in the documentation context the type is allways in front of the name (C style) while FB allows to swap the order (and in FB parameter lists the name must be in front of the type),

fb-doc can also generate real C types. In this case the above example gets

char* VarName;

and this syntax can be used direrctly by a C compiler (this can be useful to auto-generate C headers with fb-doc, ie for a library written in FB that should be used in a C project).

# Gtk-doc

Note
  This example is based on a system wide installation of fb-doc and a setting as Geany custom command with option –geany. (See Geany IDE Installation for details.))

This example is about documenting a function and its parameter list. We load our source code in to Geany IDE, select the function declaration (the code in the following bix) and send it to the fb-doc custom command:

FUNCTION goo_axis_new CDECL( _
BYVAL Parent AS GooCanvasItem PTR, _
BYVAL Back AS GooCanvasItem PTR, _
BYVAL Text AS gchar PTR, _
BYVAL Modus AS GooAxisType, _
...) AS GooAxis PTR

fb-doc extracts the names of the function and its parameters, generates a matching template and returns the customized template and the original code. The entries for the individual documentation text are marked with then text FIXME:

/'*
goo_axis_new:
@Parent: FIXME
@Back: FIXME
@Text: FIXME
@Modus: FIXME
@...: FIXME
FIXME
Returns: FIXME
`/
FUNCTION goo_axis_new CDECL( _
BYVAL Parent AS GooCanvasItem PTR, _
BYVAL Back AS GooCanvasItem PTR, _
BYVAL Text AS gchar PTR, _
BYVAL Modus AS GooAxisType, _
...) AS GooAxis PTR

Now we complete the documentation comment by filling the entries marked by the text FIXME, and we end-up with something like:

/'*
goo_axis_new:
@Parent: the parent item, or %NULL. If a parent is specified, it
will assume ownership of the item, and the item will
automatically be freed when it is removed from the
parent. Otherwise call g_object_unref() to free it.
@Back: the background box to connect the axis to (a
#GooCanvasRect, #GooCanvasImage, #GooCanvasGroup, ...).
Note: to set the axis position and size, the properties
#GooCanvasItemSimple:x, #GooCanvasItemSimple:y,
#GooCanvasItemSimple:width and
#GooCanvasItemSimple:height will be red (and therefore
must be set in the background box item).
@Text: the label text for the axis
@Modus: the position and type (like %GOO_AXIS_SOUTH or
%GOO_GRIDAXIS_SOUTH, ...)
@...: optional pairs of property names and values, and a
terminating %NULL.
Creates a new axis item.
Returns: (transfer full): a new axis item.
`/
FUNCTION goo_axis_new CDECL( _
BYVAL Parent AS GooCanvasItem PTR, _
BYVAL Back AS GooCanvasItem PTR, _
BYVAL Text AS gchar PTR, _
BYVAL Modus AS GooAxisType, _
...) AS GooAxis PTR

Finally we translate all FB sources (*.bas and *.bi) to C source using

fbdoc --asterix --fileoutput

The files gets written to the path ../doc/c_src and the output in the corresponding .c file looks like

    /**
    * goo_axis_new:
    * @Parent: the parent item, or %NULL. If a parent is specified, it
    *          will assume ownership of the item, and the item will
    *          automatically be freed when it is removed from the
    *          parent. Otherwise call g_object_unref() to free it.
    *   @Back: the background box to connect the axis to (a
    *          #GooCanvasRect, #GooCanvasImage, #GooCanvasGroup, ...).
    *          Note: to set the axis position and size, the properties
    *          #GooCanvasItemSimple:x, #GooCanvasItemSimple:y,
    *          #GooCanvasItemSimple:width and
    *          #GooCanvasItemSimple:height will be red (and therefore
    *          must be set in the background box item).
    *   @Text: the label text for the axis
    *  @Modus: the position and type (like %GOO_AXIS_SOUTH or
    *          %GOO_GRIDAXIS_SOUTH, ...)
    *    @...: optional pairs of property names and values, and a
    *          terminating %NULL.
    *
    * Creates a new axis item.
    *
    * Returns: (transfer full): a new axis item.
    * */
    FUNCTION_CDECL_AS_GooAxis_PTR goo_axis_new (
    BYVAL_AS_GooCanvasItem_PTR Parent,
    BYVAL_AS_GooCanvasItem_PTR Back,
    BYVAL_AS_gchar_PTR Text,
    BYVAL_AS_GooAxisType Modus,
    ...) {

    };

This fb-doc C-like output can be used as input for the gtk-doc tool-chain to generate the desired documentation output. The tools operate on the files in the ../doc/c_src folder.

# Doxygen

Note
  This example is based on a system wide installation of fb-doc and a setting as Geany custom command with option –geany doxy. (See Compiling and Installing for details.))

We load our code in to Geany IDE, select some source like the following code and send it to the fb-doc custom command:

    FUNCTION goo_axis_new CDECL( _
      BYVAL Parent AS GooCanvasItem PTR, _
      BYVAL Back AS GooCanvasItem PTR, _
      BYVAL Text AS gchar PTR, _
      BYVAL Modus AS GooAxisType, _
      ...) AS GooAxis PTR

fb-doc extracts the names and returns the customized template, followed by the original code:

    /'* \fn FUNCTION_CDECL_AS_GooAxis_PTR goo_axis_new (BYVAL_AS_GooCanvasItem_PTR Parent, BYVAL_AS_GooCanvasItem_PTR Back, BYVAL_AS_gchar_PTR Text, BYVAL_AS_GooAxisType Modus, ...)
    \param Parent FIXME
    \param Back FIXME
    \param Text FIXME
    \param Modus FIXME
    \param ... FIXME

    \brief FIXME

    \returns: FIXME

    FIXME

    `/
    FUNCTION goo_axis_new CDECL( _
      BYVAL Parent AS GooCanvasItem PTR, _
      BYVAL Back AS GooCanvasItem PTR, _
      BYVAL Text AS gchar PTR, _
      BYVAL Modus AS GooAxisType, _
      ...) AS GooAxis PTR

The first line is the declaration of our function in C syntax — without the character ; at the end and prepended by the keyword \fn . This line enables Doxygen to read the documentation comment anywhere in its input, so the documentations comment needs not to be in front of the matching function. Since we won't move the block (it's advantageous to place the documentation text near to the source code) we remove this line and then we complete the documentation comment by filling the entries marked by the text FIXME. We end-up with something like:

    /'*
    \param Parent the parent item, or %NULL. If a parent is specified, it
              will assume ownership of the item, and the item will
              automatically be freed when it is removed from the
              parent. Otherwise call g_object_unref() to free it.
    \param Back the background box to connect the axis to (a
              #GooCanvasRect, #GooCanvasImage, #GooCanvasGroup, ...).
              Note: to set the axis position and size, the properties
              #GooCanvasItemSimple:x, #GooCanvasItemSimple:y,
              #GooCanvasItemSimple:width and
              #GooCanvasItemSimple:height will be red (and therefore
              must be set in the background box item).
    \param Text the label text for the axis
    \param Modus the position and type (like %GOO_AXIS_SOUTH or
              %GOO_GRIDAXIS_SOUTH, ...)
    \param ... optional pairs of property names and values, and a
              terminating %NULL.

    \brief Creates a new axis item.

    \returns: a new axis item.

    A detailed desription of the function may follow here ...

    `/
    FUNCTION goo_axis_new CDECL( _
      BYVAL Parent AS GooCanvasItem PTR, _
      BYVAL Back AS GooCanvasItem PTR, _
      BYVAL Text AS gchar PTR, _
      BYVAL Modus AS GooAxisType, _
      ...) AS GooAxis PTR

    ' ...
    END FUNCTION

Using Doxygen we don't need to generate intermediate C source code in files. Instead this code gets directly piped by fb-doc acting as a filter, so we usually don't see it. Being curious we may generate files by using fb-doc with option –fileoutput and see output like

/**
\param Parent the parent item, or %NULL. If a parent is specified, it
will assume ownership of the item, and the item will
automatically be freed when it is removed from the
parent. Otherwise call g_object_unref() to free it.
\param Back the background box to connect the axis to (a
#GooCanvasRect, #GooCanvasImage, #GooCanvasGroup, ...).
Note: to set the axis position and size, the properties
#GooCanvasItemSimple:x, #GooCanvasItemSimple:y,
#GooCanvasItemSimple:width and
#GooCanvasItemSimple:height will be red (and therefore
must be set in the background box item).
\param Text the label text for the axis
\param Modus the position and type (like %GOO_AXIS_SOUTH or
%GOO_GRIDAXIS_SOUTH, ...)
\param ... optional pairs of property names and values, and a
terminating %NULL.
\brief Creates a new axis item.
\returns: a new axis item.
The detailed desription of the function follows here ...
*/
FUNCTION_CDECL_AS_GooAxis_PTR goo_axis_new (
BYVAL_AS_GooCanvasItem_PTR Parent,
BYVAL_AS_GooCanvasItem_PTR Back,
BYVAL_AS_gchar_PTR Text,
BYVAL_AS_GooAxisType Modus,
...) {
};