25.1 Structured Aldor Documentation

Aldor provides a special form of comments, so-called descriptions (cf. p. 28 of the Aldor User Guide) which are introduced via +++ (pre-description) or ++ (post-description). Such descriptions (also known as documentation comments) are tightly connected to the source code and are taken care of by the Aldor compiler. The compiler puts such descriptions into the compiled .ao file.

Unfortunately, there is no guideline how such descriptions should be structured in order to be useful for the generation of a hyperlinked API documentation. In fact, this missing guideline might be the reason why there is no program that extracts the descriptions from the .ao files and produces a hyperlinked API documentation.

The program AldorDoc by Yannis Chicha was an attempt in this direction but is currently not further pursued.

Another approach is that of Niklaus Mannhart who produced a LATEX class file aldoc. Although this class provides many useful commands for an API documentation, it suffers from its somewhat complicated user interface. Furthermore, aldoc does not take into account that part of the documentation could be generated from the corresponding Aldor source code. Insofar is aldoc disconnected from the source code and there is the danger that the documentation does not match the actual source code.

The aldordoc¹⁶ style file provided here tries to be in both spirits. It is intended to be used inside ++ and +++ descriptions and thus structuring those descriptions similar to aldoc. Furthermore, aldordoc is kept reasonably simple. Scripts should be applied to extract information from the source code and add it to the documentation.

Instead of being a LATEX class file like aldoc, aldordoc is a LATEX package. A LATEX package format enables the use of aldordoc also for the documentation by means of ALLPROSE (Aldor Literate Programming Support Environment). Literate programs are anyway the proposed form of documenting Aldor source files. The generation of an API documentation is considered to be a useful add-on. An API documentation is sometimes a form that lets a programmer easily find a function or type he/she needs.

All commands and environments of the user interface start with the prefix ad (Aldor documentation).

The interface is divided into two parts:

1. the user interface for the documentation writer and
2. the extended user interface for the program that enriches/completes the user documentation by placing anchors to the definition of types and functions inside the documentation. Part of this interface can also be used by documentation writers, in particular those commands that are not generated by the above program.