Description

The Rulebook Generator (RbG for short) is a new tool intended for the generation of high-quality documentation from annotated source code of scientific and engineering applications. RbG extracts mathematical formulae and decision tables from program statements by means of static code analysis and generates corresponding documentation in the Open Document Format or LaTeX. Annotations in source code comments are used to define the structure of the generated documents, include additional textual and graphical descriptions, and control extraction of formulae on a fine grained level. Furthermore, RbG provides an interpreter to generate function plots for extracted formulae. 

RbG was originally designed and implemented to automatically extract technical documentation from Fortran programs in electrical engineering domain. In that scenario, a Fortran programmer annotates his program by special tags and generates the corresponding documentation. In the meantime, RbG is also used to analyze programs implemented in the C/C++ programming languages. RbG comes as command line tool, as integration with the Visual Studio, and as an online service.

Video

RBG Source Code Documentation Tool

Usage

You can explore RbG (C code only) at codeanalytics.scch.at.

Basically, you upload or write some program code in the C programming language and run RbG. In order to achieve more sophisticated results you may provide some additional code annotations.

  • Use @symbol annotation to improve typesetting of variable names in generated documents. You can annotate local variables (e.g. double x; // @symbol \vec{v}) or function parameters (e.g. // @param p @symbol X_{\alpha}). Symbols may be specified by a very limited subset of LaTeX commands including greek letters (e.g. \alpha), subscript and accents (e.g. \vec).
  • Use @symbol[dectab2] to represent a decision table as a two-dimensional table.
  • Use @symbol[decbracket] to represent a decision table in classical mathematical style.
  • Use @substitute to trigger algebraic substitution of variables by last expression (e.g. double x; // @substitute).
  • Use @suppress to suppress formulae, i.e. assignments to a variable are not included in generated document (e.g. double x; // @substitute).
  • Use @plot annotation to generate a function plot for a C function. Assuming a C function double func(double a, double b), the annotation @plot(a=42, b=0:100)[color=blue]{func} generates a function plot with parameter b rendered as x-axis (range 0 to 100). The @plot annotation must be surrounded with @begindiagram and @enddiagram.

RbG provides much more tags that do not make sense in the online demo (e.g. to include texts or graphics from external files).

Implementation

RbG is implemented in the Java programming language and uses Open Fortran Parser (http://fortran-parser.sourceforge.net/) to parse Fortran files and Eclipse CDT (http://eclipse.org/cdt/) to parse C/C++ files. The intermediate representation of program code is based on the ASTM (http://www.omg.org/spec/ASTM/1.0/) standard from OMG. The Apache ODF Toolkit (https://incubator.apache.org/odftoolkit/odfdom/ ) facilitates document generation in the Open Document Format.

Presentation

Publications

J. Pichler, “Extraction of documentation from Fortran 90 source code: An industrial experience,” in 17th European Conference on Software Maintenance and Reengineering, CSMR 2013, Genova, Italy, March 5-8, 2013, pp. 399–402.

C. Klammer and J. Pichler, “Towards tool support for analyzing legacy systems in technical domains,” in 2014 Software Evolution Week - IEEE Conference on Software Maintenance, Reengineering, and Reverse Engineering, CSMR-WCRE 2014, Antwerp, Belgium, February 3-6, 2014, pp. 371–374.