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
by
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.


Contents

  • Introduction
  • The doctext Program
  • Getting Started
  • Structured Comments
  • C Routines
  • C Macros
  • Miscellaneous Documentation
  • Indicating Special Limitations
  • Indicating Include Files
  • Special Formatting
  • Describing Arguments
  • Common Blocks of Text
  • Line Breaks
  • Verbatim Blocks of Text
  • Emphasis
  • Code and Filename Font
  • Pictures
  • Verbatim
  • Keywords
  • Other Formatting Options
  • Command Line Arguments
  • Man Pages for Hypertext Documents
  • Generating Collections of Linked Web Pages
  • Alternate Formatting for HTML
  • Making a Reference Manual
  • Making the man Pages Available
  • Customizing the Output Format
  • The Doctext Commands
  • Commands
  • The Definition Command Language
  • Examples of Command Definition
  • Installing doctext
  • Acknowledgment