 |
fbdoc
1.0.1
FreeBASIC documentation tool
|
|
|
fbdoc
1.0.1
FreeBASIC documentation tool
|
|
fbdoc operates on input and generates output, that is either pipe streams (STDIN and STDOUT) or to files. The run mode determines which kind of input to get, where to get it from and where to write the output at, see first table in section Executable for an overview.
This chapter contains detailed informations on the different file types used by fc-doc for input or output. Here's a grafical overview
Input files get read in all run modes except –geany-mode (-g). At least one file of the first catagory (*.bas / *.bi) is used in any case. The other files are used by specific emitters and run modi.
The standard input of fbdoc is FreeBASIC source code, stored in files with the suffix *.bas or *.bi. The Parser is designed to operate on this files. It doesn't evaluate all the code, just documentation related constructs get sent to the related emitter functions.
fbdoc is designed to operate on error-free source code. Usually the documentation gets done after the code has been checked. So fbdoc contains just a minimal set of syntax checks, it relys on input previously validated by the FB compiler.
The suffix means List of File Names. This file is optional. It's used by emitter C_Source in order to generate caller / callee graphs and it's located in the Doxygen folder near the configuration file Doxyfile.
The file usually gets generated by fbdoc in run mode –list-mode (-l) with its default emitter FunctionNames, but editing manualy by any text editor is also possible. The file contains a comment in the first line, followed by list of function names, one name per line. Entries for member functions contain the class name and the function name, separated by a dot. The lines are separated by new line characters. (Only !"\n", but no !"\c" is allowed, so be careful when editing the file on non-LINUX systems.)
Those names are used to generate calls in function bodies in the pseudo C intermediate syntax for Doxygen back end.
Background: When fbdoc runs as a Doxygen filter (default mode), it gets called for a single input file and pipes output to STDOUT. At this moment, fbdoc doesn't know about function declarations in the other source files.
In order to generate caller / callee graphs by Doxygen, the output must contain the function calls in the function bodies. To generate those function calls in the intermediate format, fbdoc checks the words before brackets in a function body. If such a word is a symbol (no keyword), it can either be an array or a function call. fbdoc needs further information to determine the correct type and to make the decision if to function call should generated in the output stream for that word.
Since the symbol may be defined in an other file in the source tree and fbdoc operates on a single file only, the names of the functions in all source files get read from an external file. When a symbol found in a function body matches an entry in this file, a function call gets generated in the output stream. (This is a pseudo call with empty parameter list, fbdoc doesn't support OVERLOADed functions yet.)
This is an external file format, designed and used as configuration file for Doxygen. The file is located in the Doxygen directory. fbdoc evaluates it in order to operate on the same input and output as Doxygen. It's used for run modi –list-mode (-l) and –syntax-mode (-s).
Find details in the description of function Highlighter.doDoxy().
INPUT only the first source path get parsed. So make sure that your path to the FB source code is at first place when you've more than one path in the list.In run mode –syntax-mode (-s) fbdoc reads special html files generated by Doxygen (tags GENERATE_HTML = YES and SOURCE_BROWSER = YES), containing the source code listings. Doxygen generates them in the path specified by the tags OUTPUT_DIRECTORY = and HTML_OUTPUT =. The contents is based on the intermediate pseudo C format (= the filtered output of fbdoc) and therefor not useful for the documentation. fbdoc can update those files, using the real Fb source code and applying Doxygen links and style information.
The emitter SyntaxHighlighting skips the file header and parses the middle part (the listing) for hyper links. Those get collected in a list to transfer them when the file update gets created.
In run mode –syntax-mode (-s) fbdoc reads special tex files generated by Doxygen (tags GENERATE_LATEX = YES and SOURCE_BROWSER = YES), containing the source code listings. Doxygen generates them in the path specified by the tags OUTPUT_DIRECTORY = and LATEX_OUTPUT =. The contents is based on the intermediate format (= the filtered output of fbdoc) and therefor not useful for the documentation. fbdoc can update those files, using Doxygen like style information on the real Fb source code.
The emitter SyntaxHighlighting skips the file header and parses the middle part (the listing) for hyper links. Those get collected in a list to transfer them when the file update gets created.
In run mode –syntax-mode (-s) fbdoc reads special xml files generated by Doxygen (tags GENERATE_XML = YES and SOURCE_BROWSER = YES), containing the source code listings. Doxygen generates them in the path specified by the tags OUTPUT_DIRECTORY = and XML_OUTPUT =. The contents is based on the intermediate format (= the filtered output of fbdoc) and therefor not useful for the documentation. fbdoc can update those files, using Doxygen like style information on the real Fb source code.
The emitter SyntaxHighlighting skips the file header and parses the middle part (the listing) for hyper links. Those get collected in a list to transfer them when the file update gets created.
Those files are optional, used in order to extend the fbdoc features. fbdoc has an interface for external emitter modules (= plugins). These are executable binaries, compiled and linked as a library for dynamic linkage, either by using the FreeBASIC compiler or any other compiler / linker combination able to create shared libraries. Those files may have any name and get the system specific file name extension (suffix .so on LINUX or .dll on other systems). See External Emitters for details.
An external emitter can get used in any run mode. It gets specified by option –emitter (-e). The binary gets loaded at run-time.
Output files get generated by fbdoc depending on the run mode. The context of the output files depend on the emitter in use. In case of a customized emitter setting (option –emitter (-e)) make sure that the emitter generates reasonable context for the output files specified by the given run mode (find an overview in the first table in Executable).
Those files get generated in run mode –file-mode (-f) (ie. by default emitter C_Source). They contain the C-like intermediate format, transformed from the FB source input. The base file name stays unchanged, and the suffix depends on the input file name: files with suffix .bas get suffix to .c, all other input files get suffix .h.
By default those files get written to the path ../c_src, overriding existend files. Customize the default output folder setting by option –outpath (-o).
This file gets generated in run mode –list-mode (-l) by emitter FunctionNames. It contains the list of function names, used by the emitter C_Source. Place (and generate) this file in the Doxygen folder near the Doxygen configuration file, since fbdoc searches for that file in the current directory when running as a Doxygen filter.
Those files get generated in run mode –syntax-mode (-s) by emitter SyntaxHighlighting when in the Doxygen configuration file Doxyfile the tags GENERATE_HTML and SOURCE_BROWSER are both set to YES. They are located in the folder specified by the tags OUTPUT_DIRECTORY = and HTML_OUTPUT =. In the original state (after being generated by Doxygen) the files contain source code listings generated by Doxygen based on the intermediate pseudo C syntax.
fbdoc updates the files by copying the original header and footer unchanged, but replacing the middle part with source listings based on the original FB contents. FB keywords get highlighted and hyper links from symbols to the text description get transfered to the new context. During this process, a temporary file with suffix *.html_ gets generated and removed after successful operation.
Those files get generated in run mode –syntax-mode (-s) by emitter SyntaxHighlighting when in the Doxygen configuration file Doxyfile the tags GENERATE_LATEX and LATEX_SOURCE_CODE are both set to YES. They are located in the folder specified by the tags OUTPUT_DIRECTORY = and LATEX_OUTPUT =. In the original state (after being generated by Doxygen) the files contain source code listings generated by Doxygen based on the intermediate pseudo C syntax.
fbdoc updates the files by copying the original header and footer unchanged, but replacing the middle part with source listings based on the original FB contents. FB keywords get highlighted and hyper links from symbols to the text description get transfered to the new context. During this process, a temporary file with suffix *.tex_ gets generated and removed after successful operation.
Those files get generated in run mode –syntax-mode (-s) by emitter SyntaxHighlighting when in the Doxygen configuration file Doxyfile the tags GENERATE_XML and XML_PROGRAMLISTING are both set to YES. They are located in the folder specified by the tags OUTPUT_DIRECTORY = and XML_OUTPUT =. In the original state (after being generated by Doxygen) the files contain source code listings generated by Doxygen based on the intermediate pseudo C syntax.
fbdoc updates the files by copying the original header and footer unchanged, but replacing the middle part with source listings based on the original FB contents. FB keywords get highlighted and hyper links from symbols to the text description get transfered to the new context. During this process, a temporary file with suffix *.tex_ gets generated and removed after successful operation.
In rare cases fbdoc works with fixed directory settings.
fbdoc currently uses two types of external files, loaded from the current directory:
It tries to load the context when needed. When loading fails, it operates without the required information in the first case. And in the second case it stopd, since it cannot operate without an emitter. fbdoc searches for the files in the EXEPATH (the folder of the fbdoc binary).
This folder gets created by fbdoc to write the file output. It's used to collect the translations from the C_Source emitter. The back-end read its input from here. The folder gets created above the source code folder (= at the same level as the source code folder).
1.9.1