 |
fb-doc
0.4.0
FreeBASIC documentation tool
|
|
|
fb-doc
0.4.0
FreeBASIC documentation tool
|
|
Emitters generate the output of fb-doc, which gets either written to the stream STDOUT or to files, depending on the choosen run mode. An emitter provides a set of functions of type EmitFunc, specified in the class EmitterIF. When the parser evaluates the (FB source) input and finds a documentation related construct, it calls the emitter function for that type of code. The emitter function transforms the FB source context to the desired output format, either by using parser information (provided in variables in the Parser structure) or by further evaluation of the source code. Documentation related constructs are
| Construct | Keywords |
|---|---|
| variables | VAR DIM REDIM CONST COMMON EXTERN STATIC |
| blocks | ENUN UNION TYPE CLASS |
| forward declarations | DECLARE TYPE TYPE alias |
| functions | SUB FUNCTION PORPERTY CONSTRUCTOR DESTRUCTOR |
| macros | #DEFINE #MACRO |
| includes | #INCLUDE |
fb-doc gets shipped with inbuild emitters for the standard tasks. It also contains an interface for external emitters (= plugins) to extend its features.
Inbuild emitters are compiled in to the executable binary. You can use them out-of-the-box.
This emitter is designed to generate the (C-like) intermediate format for the documentation generating backends. It translates all related constructs and transfers all documentaional comments (but no local comments). Each construct gets placed at the same line as in the FB source.
At start-up, the emitter tries to load the file fb-doc.lfn. If present (in the current directory), the output contains pseudo function calls in function bodies, in order generate caller / callee graphs in Doxygen output. A pseudo call is composed of the function name and an pair of empty brackets (no parameters).
This emitter is designed to generate templates for gtk-doc, when fb-doc is used as a filter for Geany IDE. It generates documentational comment blocks in the gtk-doc format for all related constructs. The output contains the newly created, empty comment block and the original source code. Usually the related construct gets selected in an editor and the filter auto-generates the matching documentational comment block. Finally the user fills in the description texts.
When the input is an empty block in --geany-mode (-g), the emitter creates a comment block for documenting the file (@SECTION tag).
This emitter is designed to generate templates for Doxygen, when fb-doc is used as a filter for Geany IDE. It generates documentational comment blocks in the Doxygen format for all related constructs. The output contains the newly created, empty comment block and the original source code. Usually the related construct gets selected in an editor and the filter auto-generates the matching documentational comment block. Finally the user fills in the description texts.
Usually separate comment blocks are not necessary for Doxygen backend, since the documentation can get placed right before or behind the related construct. The only exception is the documentation of functions, which uses a comment block to list the parameters and the return value. (As an experimental feature, Doxygen also supports to place the documentational comments at other locations, ie. in a separate file.)
When the input is an empty block in --geany-mode (-g), the emitter creates a comment block for documenting the file (\ file tag).
This emitter is designed to generate the file fb-doc.lfn. It skips most of the related constructs, but exports the names of all functions, one in a row, separated by carriage return (CR = "\\r") characters.
It works on SUB FUNCTION and PORPERTY bodies. In case of member functions the UDT name and the function name gets emitted.
This is a complex emitter, designed to generate source code listings for Doxygen output in different file formats (.html, .tex and .xml). By default Doxygen generates those listings based on the output of the filter defined by the tag FILTER_SOURCE_PATTERNS, which should be the intermediate (C-like) format (in order to get correct graphs). This means the original Doxygen listing files contain C-like) syntax. The files can get overriden by this emitter, generating context from the FB source code with correct syntax highlighting and hyperlinks to the documentation.
For convenience and easy handling, this emitter determines the input files by evaluating the Doxygen configuration file:
INPUT. The scanning is recursiv dependent on the setting of tag RECURSIVE.OUTPUT_DIRECTORY combined with | path | when those switches are set to YES |
|---|---|
HTML_OUTPUT | GENERATE_HTML SOURCE_BROWSER |
LATEX_OUTPUT | GENERATE_LATEX LATEX_SOURCE_CODE |
XML_OUTPUT | GENERATE_XML XML_PROGRAMLISTING |
CREATE_SUBDIRS.Each output file gets overriden by a similar file with identical header and footer, but newly generated listing body with FB code. The body contains syntax highlighting by the style classes keyword, keywordtype, keywordflow, preprocessor, comment and stringliteral, which are defined by the original Doxygen output. Special characters get transformed to the file encoding, depending on the output format (HTML, TEX or XML). And original hyperlinks between the source and the documentation get transfered to the new body.
The emitter also provides a simple use case to operate on source files directly (suffix .bas or .bi instead of a Doxygen configuration file). In that case to output is in HTML format only and it gets sent to STDOUT. See also the note in section #SecModSyntax.
An external emitter is an executable binary compiled as a shared library. fb-doc loads that binary at run-time and uses its EmitterIF to generate the output. The EmitterIF can manipulate the related constructs in any customized manner and can create arbitrary output formats.
The input and output is dependend on the run mode, see section Run Modi for an overview. Since the fb-doc file formats may not match the output format generated by the plugin, in most cases run modi outputing to STDOUT will be used. That output can get piped to files. Dependend on the desired input use none (default) for file input or --geany-mode (-g) for input from STDIN. (You can also pipe file context to mode --geany-mode (-g).)
Before you can use an external emitter, the source code has to get developed and compiled, see section SecPluginDev for details. In order to load the plugin, the binary has to be located in the current directory.
SOURCE.bas, the compiler generates a binary file named libSOURCE.so (or libSOURCE.dll on non-LINUX systems). To load that binary use --emitter SOURCE. 
1.8.11