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

This page contains some information on fb-doc in table format.

# Options

Table of all fb-doc options. An option starts by a minus character followed by a single character (short form) or by two minus characters followed by a word (long form). Both forms have the same meaning.

Each word in the command line without the leading '-' character gets interpreted as a file name or pattern (ie a string in single or double quotes). The only exeptions are the (may be qouted) strings right behind the –emitter or –path options, which gets interpreted as a path or emitter name.

Option | Parameter | Description
--- | --- | ---
-a or –asterix | none | emit lines in a multi line comment block with leading '* ' characters (gtk-doc style)
-c or –cstyle | none | emit types in real C syntax (instead of FB styled pseudo C syntax)
-e or –emitter | Emitter name | Use the specified emitter. Standard emitters are named C_Source, ListOfFunction, GtkDocTemplates and DoxygenTemplates. fb-doc will compare the specified name with each emitter name and apply this emitter if there is a match. Comparison is done non-case-sensitve and just the given characters are compared, so ie dox matches DoxygenTemplates. If no match is found, fb-doc tries to load and use an external emitter module as a dynamic linked library from its EXEPATH. If there is no such modul, the standard emitter is used (each run mode has its own standard emitter).

-f or –fileoutput | none | scan the current folder for file(s) or pattern(s) and create similar C source including comments in the folder ../doc/c_src. When no filename or pattern is specified, all *.bas and *.bi files gets translated.
-g or –geany | Emitter name | read input from StdIn (normaly send in Geany to receive the selected text block, default emitter is GtkDocTemplates)
-h or –help | none | print the help text and stop
-l or –list | filename or pattern | scan the current folder for one file, a file pattern or all FbreeBasic source files *.bas and *.bi and collect the names of all functions. Write them in to the file fb-doc.lfn (override existing or create new if not exist). This file is used to create caller and callee graphs with Doxygen back-end.

-p or –path | path name | specify the folder to start scanning
-r or –recursiv | none | scan input files in the current folder and all subfolders
-t or –tree | none | scan the source tree and follow all #INCLUDE statements
-v or –version | none | print the version information and stop

Note
  An empty command line makes fb-doc to output the help text (as if option –help was given).
  In case of interaction between multiple options the latest is the dominant (see Input / Output for details).

# Inbuild Emitters

fb-doc comes with four inbuild emitters to target different goals. Option –emitter (-e) is used to choose the one in use. (There cannot be more than one emitter in use.)

Inbuild emitters can be specified by the complete name or just a part of it. fb-doc compares all characters of the (non-quoted) word behind the –emitter option against the names of the inbuild emitters (non-case-sensitive), as listed in the following table.

Beside inbuild emitters also external emitters can be used by specifying the library name after the –emitter option (full name including suffix, case sensitive on LINUX). A quoted string gets allways interpreted as a library name. See Extending fb-doc and Options::chooseEmitter() for further information.

Name | Prefered Mode | Function
--- | --- | ---
C_Source | gtk-doc or Doxy-Filter | Emit translated FB source in (pseudo) C syntax (default) or real C syntax (option –cstyle)
GtkDocTemplates | Geany | Generate templates for gtk-doc (default in –geany mode). This emitter doesn't support the option –tree.
DoxygenTemplates | Geany | Generate templates for Doxygen. This emitter doesn't support the option –tree.
Callees | create fb-doc.lfn | Emit all function names to be used in a further run in Doxy-Filter mode (default in –list mode)

Note
  It's recommended to specify an internal emitter by its (non-quoted) name and external emitter moduls by a quoted string.

# Input / Output

Some options control the execution of fb-doc and the streams of input and output data. The following table shows the relations between working mode and input / output targets:

Run-Mode | Option | Input | Output | Default Emitter
--- | --- | --- | --- | ---
Doxy-Filter | none | one file | standard out (StdOut) | C_Source
gtk-doc | -f or –fileoutput | one file, files matching a pattern or all source files | *.c and *.h files | C_Source
Geany templates | -g or –geany | standard in (StdIn) | standard out (StdOut) | GtkDocTemplates
List-Generation | -l or –list | files matching a pattern or all source files | file fb-doc.lfn | Callees
Help | -h or –help | none | standard out (StdOut) | none
Info | -v or –version | none | standard out (StdOut) | none

Note
  the default mode is the Doxygen filter mode, since Doxygen doesn't allow to send further options (directly).
  Input and output channels are fixed to the listed options. But you can apply changes, ie by specifying an other the emitter with –emitter option or input more than one file by walking through the source tree with –tree option, ...
  The modi –help (-h) and –version (-v) are not related to any FB source. Instead of using an emitter they create fixed output on standard output channel (StdOut).
  When more then one run mode is specified in the command line, the latest is the dominant.

# File Names

Any text in the command line not matching an option or its parameter gets interpreted as a file name or file pattern. They get added to a queue and fb-doc executes this queue in the given order. Depending on the file name and the run mode fb-doc operates in different ways:

Option (run-mode) | no name | exact name | pattern
--- | --- | --- | ---
default | print help text | load file, emit output to StdOut | load all files matching the pattern, emit output to StdOut
-f or –fileoutput | load all *.bas and *.bi files, emit output for each file to a *.c or *.h file | load this one file, scan the source tree and load each #INCLUDE file, emit output for each file to a *.c or *.h file | load all files matching the pattern, emit output for each file to a *.c or *.h file
-g or –geany | ignored | ignored | ignored
-l or –list | load all *.bas and *. bi files, emit output to one file named fb-doc.lfn | load this one file, scan the source tree and load each #INCLUDE file, emit output to one file named fb-doc.lfn | load all files matching the pattern, emit output to one file named fb-doc.lfn

Note
  A file name may be prepended by a relative or an absolute path.
  File names or paths including a space character have to be enclosed by single or double qoutes.
  Multiple file names get separated by a space character or by a ; character.
  A file name cannot start with a minus character and cannot include single or double quote characters.

# Type Mangling

fb-doc mangles the keywords of a FB type declaration in to a single word, separated by an underscore character. The following table contains some examples. This mangling can get suppressed by option –cstyle, to get real C types emitted.

FB source | default | –cstyle
--- | --- | ---
DIM AS INTEGER Nam | INTEGER Nam | int Nam
DIM Nam AS INTEGER | INTEGER Nam | int Nam
CONST Nam AS INTEGER | CONST_INTEGER Nam | const int Nam
Extern Nam AS INTEGER | Extern_INTEGER Nam | extern int Nam
DECLARE PROPERTY CurTok() AS INTEGER PTR | PROPERTY_AS_INTEGER_PTR CurTok() | int *CurTok(void)
BYVAL Export_ AS EmitFunc | BYVAL_AS_EmitFunc Export_ | EmitFunc *Export_
byref Z as byte | byref_as_byte Z | char *Z
byval Z as byte | byval_as_byte Z | char Z

# Undocumented files

The src folder in the fb-doc archive contains two more files, which are not included in the files list in this ducumentation. These are files used by Doxygen, check its manual for details:

Name | Function
--- | ---
Doxyfile | A configuration file, controlling the Doxygen operation.
DoxygenLayout.xml | A configuration file, controlling the index context of these html pages.