Examples

Table of Contents

• Documentational Comments
• Command Line Interface
• Workflow
  • Doxygen
  • gtk-doc

Documentational Comments

In the development process of a software project some source code gets designed and a compiler (or interpreter) transforms that source code to executable assembler commands for the CPU. In a similar way a documentation tool scans the source code and transforms data to generate documentation for the user. Simple tools extract information from special comments marked by (one or more) magic character. All context for the documentation is in the comments, created by the programmer. Advanced tools like Doxygen also scan the source code (and the special comments), in order to read information like symbol names, class declarations, ... Scanning the source code avoids redundant information and helps to keep the documentation up to date.

Command Line Interface

In order to get familiar with the command line interface here are some exercises, operating fbdoc on its own source code. It's presumed that you compiled and installed the executable in a system path, so that you can call it from any folder (see section Build for details). Otherwise you have to prepend the complete path to execute the binary.

Note

Execute the commands in the source code folder src/bas.

Lines starting with a $ character are the commands executed at the terminal. The other lines are output.

1. To output information about your executable binary execute

   $ fbdoc --version
   fbdoc: version 0.4.0, License GPLv3
        Copyright (C) 2012-2016 by Thomas{ At ]Freiherr{ at }gmx[ dOt ]net
     Compiled: 03-04-2016, 11:32:38 for UNIX/LINUX. (FreeBASIC 1.05.0)

2. To output brief information about the available options execute

   $ fbdoc --help
   fbdoc: version 0.4.0, License GPLv3
           Copyright (C) 2012-2016 by Thomas{ At ]Freiherr{ at }gmx[ dOt ]net
   Command line tool for generating documentation from FreeBASIC source code.
    
   Usage
     fbdoc [Options] [file specs]
    
   Options:
    -h (--help)    : print this help text and stop
    -v (--version) : print version information and stop
          none         : file in --> STDOUT
    -f (--file-mode)   : file in --> file out
    -g (--geany-mode)  : STDIN --> STDOUT
    -l (--list-mode)   : Doxgfile inputs --> fbdoc.lfn
    -s (--syntax-mode) : scan doxygen output, repair syntax highlighting
    -a (--asterix)     : prepend '* ' in ML comments (gtk-doc style)
    -c (--cstyle)      : emit real C types
    -d (--doc-comment) : force documentational comments in listings
    -e (--emitter)     : specify emitter name
    -o (--outpath)     : specify output directory
    -r (--recursiv)    : scan input files also in subfolders
    -t (--tree)        : scan source tree (follow #INCLUDEs)
   Examples:
     fbdoc --geany-mode
         Get input from STDIN, prepend a matching comment block, emit to STDOUT
         (emits gtk-doc templates for ENUM, UNION, TYPE, SUB, FUNCTION, PROPERTY)
     fbdoc -f -t MyProject.bas
         Load MyProject.bas from current folder and follow source tree
         emit pseudo C code in ../c_src
   For details see file 'ReadMe.txt' or visit:
     http://www.freebasic.net/forum/viewtopic.php?f=8&t=19810 (en)

3. To see the intermediate format for a certain file (fbdoc.bas in this case) execute

   $ fbdoc fbdoc.bas

   The output in this default mode is a mixture of fbdoc messages (src/bas/fbdoc.bas --> and done, written to STDERR) and the transformed output (written to STDOUT). Both get mixed in to one stream by the terminal. The default mode is designed to be used as a Doxygen filter. In that use case the STDERR stream goes as user information to the Doxygen log and the STDOUT stream is the internal data flow (invisible).
4. In order to see only the intermediate format (without fbdoc messages) you can use –geany-mode (-g) and pipe the input to fbdoc by executing

   $ fbdoc --geany-mode < fbdoc.bas

   Compare the output with the original file and note the different format of the comments (starting with /*! and ending with */) and the include statements (removed keyword ONCE).
5. You can also separate STDERR and STDOUT streams by writing the STDOUT output to a file, executing

   $ fbdoc fbdoc.bas > out.c
    
                             fbdoc.bas --> done

   The terminal shows the messages (as in the Doxygen log) and the transformed output is in the newly created file out.c.
6. The file output can also get generated in –file-mode (-f) by executing

   $ fbdoc --file-mode fbdoc.bas
    
                             fbdoc.bas --> done

   In that case the file name gets auto-generated by fbdoc (here it's fbdoc.c) and the file gets generated in the (newly created) default path ../c_src, so check file src/c_src/fbdoc.c. In order to overridde the default path and generate the file in the current directory use option –outpath (-o), like

   $ fbdoc --file-mode --outpath "." fbdoc.bas
    
                             fbdoc.bas --> done

7. To translate all source files in –file-mode (-f) execute

   $ fbdoc --file-mode
    
                       fbdoc_emit_gtk.bas --> done
                      fbdoc_emit_doxy.bas --> done
                                fbdoc.bas --> done
                           fbdoc_main.bas --> done
                   fbdoc_emit_csource.bas --> done
                        fbdoc_options.bas --> done
                       fbdoc_emitters.bas --> done
                    fbdoc_emit_syntax.bas --> done
                       fbdoc_doxyfile.bas --> done
                       fbdoc_emit_lfn.bas --> done
                         fbdoc_parser.bas --> done
                        fbdoc_doxyfile.bi --> done
                          fbdoc_parser.bi --> done
                     fbdoc_emit_syntax.bi --> done
                        fbdoc_emitters.bi --> done
                         fbdoc_version.bi --> done
                        fbdoc_emit_lfn.bi --> done

   fbdoc scans by default all files matching the patterns *.bas and *.bi and operates on all of those files. In order to select specific files you can customize the patterns like

   $ fbdoc --file-mode "*emit*.bas" "*emit*.bi"
    
                       fbdoc_emit_gtk.bas --> done
                      fbdoc_emit_doxy.bas --> done
                   fbdoc_emit_csource.bas --> done
                       fbdoc_emitters.bas --> done
                    fbdoc_emit_syntax.bas --> done
                       fbdoc_emit_lfn.bas --> done
                     fbdoc_emit_syntax.bi --> done
                        fbdoc_emitters.bi --> done

   Note

   On LINUX you have to enclose the patterns by quotes (single or double) to pass them to fbdoc. Otherwise the shell expands the patterns.

8. To change the output format you can choose another emitter, ie. for html output execute

   $ fbdoc --emitter "Syntax" --geany-mode < fbdoc.bas

   Alternative you can use the short form

   $ fbdoc --geany-mode "Syntax" < fbdoc.bas

   In both cases the documentational comments gets stripped in the output. To add them execute

   $ fbdoc --geany-mode "Syntax" --doc-comments < fbdoc.bas

Workflow

Doxygen

gtk-doc