Users Manual for doctext: Producing Documentation from Source Code

William Gropp
Mathematics and Computer Science Division

Users Manual for doctext:
Producing Documentation from Source Code
William Gropp

One of the major problems that software library writers face, particularly in a research environment, is the generation of documentation. Producing good, professional-quality documentation is tedious and time consuming. Often, no documentation is produced. For many users, however, much of the need for documentation may be satisfied by a brief description of the purpose and use of the routines and their arguments. Even for more complete, hand-generated documentation, this information provides a convenient starting point. We describe here a tool that may be used to generate documentation about programs written in the C language. It uses a structured comment convention that preserves the original C source code and does not require any additional files. The markup language is designed to be an almost invisible structured comment in the C source code, retaining readability in the original source. Documentation in a form suitable for the Unix man program (nroff), LaTeX, and the World Wide Web can be produced. The output format is controlled by easily modified tables, permitting customization of the output. Support for other languages is also provided, though with fewer features.