Introduction
lpdoc is an automatic program documentation generator for (C)LP systems.lpdoc generates a reference manual automatically from one or more source files for a logic program (including ISO-Prolog [DEDC96], Ciao [Bue95], and other CLP [JM94] systems). It is particularly useful for documenting library modules, for which it automatically generates a description of the module interface. However, lpdoc can also be used quite successfully to document full applications and to generate nicely formatted plain ASCII ``readme'' files. A fundamental advantage of using lpdoc to document programs is that it is much easier to maintain a true correspondence between the program and its documentation, and to identify precisely to what version of the program a given printed manual corresponds.
Overview of this document
This first part of the document provides usage information on how to generate and access manuals (Generating and accessing manuals), as well as detailed instructions required to write proper documentation manuals (Writing documentation). Examples are given using the files in the examples directory provided with the lpdoc distribution.
Other parts of this document provide:
- Documentation on the syntax and meaning of the assertions that lpdoc uses (those defined in the Ciao assertions library [PBH97,PBH98,Bue98]). These include comment assertions (containing basically documentation text), formal assertions (containing properties), and combined assertions.
- Documentation on a basic set of properties, types, etc. which are predefined in the Ciao basic_props, regtypes, native_props, and meta_props libraries. These properties, and any others defined by the user or in other Ciao libraries, can be used in program assertions.
- Documentation on the formatting commands that can be embedded in comments.
A separate internals manual provides information on how the different internal parts of lpdoc are connected, which can be useful if new capabilities need to be added to the system or its libraries are used for other purposes.
All of the above have been generated automatically from the assertions in the corresponding sources and can also be seen as examples of the use of lpdoc.
Some additional information on lpdoc can be found in [Her00].