| 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
Introduction

# Introduction

In software projects it's state-of-the-art to write and edit the documentation context inside the source code. This way the programmer can adapt the documentation on each bug fix or improvement at one place (in comments placed in the source file). Beside the compiler, which extracts information for the CPU, an additional tool-chain is used to extract the information from the source code comments to build the documentation.

Powerful tool-chains (back-ends) exist for several programming languages like C to generate output in different formats, ie like html, pdf, man-pages and others. But privious to fb-doc there is nothing for FreeBasic source code yet.

Since it's a lot of work to design and test such a tool-chain for several output formats, fb-doc isn't designed as a complete tool chain. Instead it works as a bridge that closes the gap between FreeBasic and C syntax to make existing, well developed and tested C documenting back-ends usable with FreeBasic syntax. fb-doc has been tested with

- gtk-doc (see: http://developer.gnome.org/gtk-doc-manual/stable/index.html)
- Doxygen (see: http://www.doxygen.org/)

The first is a good choise if you like to document a libraries API in the GNOME documentation style. In all other cases, especially when you have to document a program or application, the later is the better choise. Doxygen is a more modern tool, it's easier to handle, comes with a GUI front-end and has more features than gtk-doc.

The steps to generate a well documented project are

1. generate source code, compile and test it
2. add documentation comments and up-date them on each change inside the source code
3. run fb-doc on the FreeBasic source code to build a C-like intermediate format
4. run the C-back-end on the intemediate format to build the documentation output in one or more output formats (ie html, pdf, manpage, ...)

This intermediate format doesn't contain complete C source and cannot get compiled by a C compiler. Instead it just includes all information the lexical scanners of the back-ends need to build the documentation output. And fb-doc itself doesn't parse the complete FreeBasic source code. Instead it also acts as a lexical scanner to extract just the necessary information. Therefor fb-doc shouldn't be executed on buggy source (, be prepared to face fancy output in that case).

# The Prinzip

First fb-doc has to copy the documenting comments from the FreeBasic source code to the intermediate format and adapt the characters starting and ending the comment from one language to the other. But since some comments may only be useful in the FB source and others should go to the documentation, fb-doc uses magic characters at the beginning of a comment to specify how to act. FreeBasic syntax allows two kinds of comments

1. line end comments starting by a ' character and ending at the line end
2. comment blocks enclosed by /' and '/

fb-doc supports both types. To get the comment emitted to the intermediate format, its first character has to be a *. In that case the context of the comment gets emitted as a similar C construct (as a line end comment starting by // or as a comment block enclosed by and ).

Note
  There's also the additional magic character '&' that makes fb-doc emit the comment context as pure C-source.

See Comments (in general) for an example.

Second the lexical scanner of the back-end needs to know the target of the documentation context. This can be a declaration of

- a variable (VAR / DIM / CONST / COMMON / EXTERN / STATIC),
- a memory block (ENUN / UNION / TYPE / CLASS),
- a forward declaration (TYPE alias),
- a function (SUB / FUNCTION / PORPERTY / CONSTRUCTOR / DESTRUCTOR) or
- a macro (#DEFINE / #MACRO).

fb-doc scans for this keywords and analyses the context. Depending on the choosen emitter it generates output in a specific way. In the default configuration (when acting as the start of a documentation tool-chain) fb-doc translates the context to C (or C-like) source.

See Variable Declaration for an example.

# Additional Features

In addition to this basic feature fb-doc offers further functionality by adapting the operation mode and emitter:

1. It can extract a list of all function names from the source code tree. The list is necessary to generate caller / callee graphs with Doxygen back-end (as in this documentation), see Doxygen Back-End for details.
2. It can generate templates inside the FB source when acting as a Geany custom command. We can mark a block of source code in Geany and send it to fb-doc. fb-doc generates a matching documentation comment block and prepends it to the source, see Generating Templates for details.

Depending on the operation mode it can input either from StdIn or files and output to StdOut or files. Piping context in and from fb-doc offers a lot more fields of application. In case of file input / output, *.bas files get translated to *.c files and .bi files translate to *.h.

Last but not least fb-doc comes with a plugin-interface. It can load and use external emitters, compiled as a dynamic loadable library (*. dll or *.so). By such an external emitter modul any output can get generated, using the informations comming from the fb-doc scanner.

An example source code for an external emitter is in the package, just customize it by your functionality. External emitter plugins may add features like

- an emitter filling a data base as input for source code analysing tools like sourcenavigator
- an emitter to generate direct output, ie html pages
- an ...

# About this Text

And finally some words about this documentation (the text you're currently reading). It is generated from FB source in the above mentioned way by using Doxygen as back-end. If you need examples for any topic just study the fb-doc source code. Beside this you may want to check the file Doxyfile in the src folder. It contains the configuration for Doxygen to extract this pages. A good start may be to use these files and create your customized fb-doc documentation and play around with the parameters.

To be honest: in some cases this documentation may be a bit overloaded and serve more information than necessary. But one of the reasons for creating it is to demonstrate the features of fb-doc and Doxygen. Therefor not all possibilities are used to reduce the output to the essentials (see the Doxygen manual for details).

Note
  It's not under the scope of this documentation to describe the usage of any (or all possible) tool-chain(s). Please refer to the respective manual(s) for further information.