This document describes how to use the HeaderDoc tool. It also explains how to insert HeaderDoc comments into your headers and other files. This document corresponds with HeaderDoc 8.0. For information about previous versions, consult the documentation installed with your HeaderDoc distribution.
HeaderDoc is a set of tools for embedding structured comments in source code and header files written in various languages and subsequently producing rich HTML and XML output from those comments. HeaderDoc comments are similar in appearance to JavaDoc comments in a Java source file, but traditional HeaderDoc comments provide a slightly more formal tag set to allow greater control over HeaderDoc behavior.
HeaderDoc is primarily intended for use on Mac OS X, as part of the Mac OS X Developer Tools. However, in various versions, it has also been used successfully on other operating systems, including Linux, Solaris, and Mac OS 9. (Your mileage may vary.)
In addition to traditional HeaderDoc markup, HeaderDoc 8 supports JavaDoc markup. HeaderDoc 8 also supports a number of languages: Bourne shell (and Korn and Bourne Again), C Headers, C source code, C shell, C++ headers, Java, JavaScript, Mach MIG definitions, Objective C/C++ headers, Pascal, Perl, and PHP. Most of these languages (besides C/C++/ObjC/Pascal) support documenting only functions or subroutines.
Also included with the main script (headerDoc2HTML) is gatherHeaderDoc, a utility script that creates a master table of contents for all documentation generated by headerDoc2HTML. Information on running gatherHeaderDoc is provided in “Advanced HeaderDoc Configuration and Features.”
Both scripts are typically installed in /usr/bin, as headerdoc2html and gatherheaderdoc.
Finally, HeaderDoc comes with a series of tools for man page generation, xml2man and hdxml2manxml. The first tool, xml2man, converts an mdoc-like XML dialect into mdoc-style man pages. The second tool, hdxml2manxml, converts HeaderDoc XML (generated with the -X flag) into a series of .mxml files suitable for use with xml2man.
You should read this document if you are interested in generating documentation from your source code, generating manual pages, or using any of HeaderDoc’s other features.
HeaderDoc is available in two ways. First, HeaderDoc is part of the standard Mac OS X Developer Tools installation. If you have installed the Developer Tools CD, it is already installed on your system.
Second, HeaderDoc can be downloaded from the Darwin source collection at http://www.opensource.apple.com/darwinsource/.
This document is divided into several chapters describing various aspects of the tool suite.
“Using HeaderDoc” explains the syntax for the HeaderDoc command-line tool itself.
“HeaderDoc Tags” explains how to add HeaderDoc markup to header (and source code) files.
“Basic HeaderDoc Configuration” explains the HeaderDoc configuration file.
“Advanced HeaderDoc Configuration and Features” explains how to use gatherHeaderDoc to produce landing pages and cross-linked trees of related documentation.
“Using the MPGL Suite” explains how to use the Manual Page Generation Language (MPGL) tool suite.
“HeaderDoc Release Notes” provides recent version history for the HeaderDoc toolchain.
“Symbol Markers for HTML-Based Documentation” describes the symbol markers used by HeaderDoc and various other utilities to provide linking functionality.
“HeaderDoc Class Hierarchy” describes the class hierarchy of the HeaderDoc tool itself.
“Troubleshooting” explains common error messages and their likely causes.
Last updated: 2009-06-23
