Back to Contents

Automatic source documentation generator

Summary:

Basics

Documenting sources is an important task in software development, to share the code among applications and achieve better reusability. Source documentation must be concise, clear, and complete. However, documenting sources can be boring and subject to mistakes if large repetitive documentation sections have to be written by hand.

Robust source documentation can be produced automatically with the fglcomp compiler. The compiler can generate source documentation from the .4gl files of your project with minimum effort. The resulting source documentation is generated in simple HTML format and can be published on a web server.

Source documentation is generated with the --build-doc option of fglcomp. You can generate default documentation from the existing sources. For a better description of the code, you can add special #+ comments in your sources to describe code elements such as functions, function parameters, and return values.

Prerequisites

To generate the HTML pages, fglcomp first generates .xa files which must be converted to .html files. The conversion from .xa to .html is done with an XSLT processor using the .xsl style sheets files provided in FGLDIR/lib/fgldoc/

You must have an XSLT processor installed on the machine where the documentation is generated.

If necessary, the style sheets provided in FGLDIR/lib/fgldoc can be adapted to transform the .xa files to .html files.

Syntax

To extract documentation from a 4gl source:

fglcomp --build-doc filename.4gl

Documentation structure

The source documentation structure is based on the well-known Java-doc technique. The generated documentation reflects the structure of your sources; in order to have nicely structured source documentation, you must have a nicely structured source tree.

The Genero BDL source documentation elements are structured as follows (elements in red must be created by hand, while the green color indicates generated files):

You must create a file named overview.4gl in the top directory of the project. This file contains the overall description of the project. In that directory, the documentation generator creates the files overview-summary.html, overview-frame.html, allclasses-frame.html, index-all.html, index.html and fgldoc.css.

The generator can scan sub-directories to build the documentation for a whole project; each source directory defines a package. For each directory (i.e. package), the generator creates a package-summary.html and a package-frame.html file. If a file with the name package-info.4gl exists, it will be scanned to complete the package-summary.html file with the package description.

The generator creates a filename.html file for each 4gl source module, seen as a class in the documentation.

Adding comments to sources

Commenting a Function

To comment a function, add some lines starting with #+, before the function body. The comment body is composed of paragraphs separated by a blank line. The first paragraph of the comment is a short description of the function. This description will be placed in the function summary table. The next paragraph is long text describing the function in detail. Other paragraphs must start with a tag to identify the type of the paragraph; a tag starts with the @ "at" sign.

Supported @ tags:

Tag Description
@code Indicates that the next lines show a code example using the function.
@param name description Defines a function parameter identified by name, explained by a description.
Note that name must match the parameter name in the function declaration.
@returnType fglType Defines the data type of the value returned by the function.
If the function returns several values, write a comma-separated list of types.
@return description Describes the values returned by the function.
Several @return comment lines can be written.
Example:
01 #+ Compute the amount of the orders for a given customer
02 #+
03 #+ This function calculates the total amount of all orders for the
04 #+ customer identified by the cust_id number passed as parameter.
05 #+
06 #+ @code
07 #+ DEFINE total DECIMAL(10,2)
08 #+ CALL total = ordersTotal(r_customer.cust_id)
09 #+
10 #+ @param cid Customer identifier
11 #+
12 #+ @returnType DECIMAL(10,2)
13 #+ @return The total amount as DECIMAL(10,2)
14 #+
15 FUNCTION ordersTotal(cid)
16    DEFINE cid INTEGER
17    DEFINE ordtot DECIMAL(10,2)
18    SELECT SUM(ord_amount) INTO ordtot
19         FROM orders WHERE orders.cust_id = cid
20    RETURN ordtot
21 END FUNCTION

Commenting a Module

To comment a 4gl module, you can add #+ lines at the beginning of the source, before module element declarations such as module variable definitions. 

Example:
01 #+ This module implements customer information handling
02 #+
03 #+ This code uses the 'customer' and 'custdetail' database tables.
04 #+ Customer input, query and list handling functions are defined here. 
05 #+
06 DEFINE r_cust RECORD
07    cust_id INTEGER,
08    cust_name VARCHAR(50),
09    cust_address VARCHAR(200)
10 END RECORD

Commenting a Package

To describe a complete directory (i.e. package), you must create a package-info.4gl file in the directory and add a #+ comment in the file. The comment will be added to the package-summary.html file.

Commenting a Project

In the top directory of your sources, you must create a overview.4gl file with a #+ comment describing the project. This file is mandatory in order to generate the tree of html pages for an entire project, as it is used as the starting point by fglcomp. See "Running the documentation generator" for more details.

Running the documentation generator

To produce the source documentation, follow these steps:

  1. Go to the TOP directory of your sources.
  2. Create a file named overview.4gl, with a #+ comment describing your project.
  3. Go to the subdirectories and create files named package-info.4gl with a #+ comment describing the package.
  4. Edit the 4gl modules to add #+ comments to functions that must be documented.
  5. Go back to the TOP directory.
  6. Run fglcomp --build-doc overview.4gl.
  7. To test the result, load the generated index.html file in your preferred browser.