Important: This document may not represent best practices for current development. Links to downloads and other resources may no longer be valid.
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.
What is HeaderDoc?
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 OS X, as part of the 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 supports a wide range of languages:
Bourne shell (and Korn and Bourne Again)
C Headers and C source code
C shell scripts
Mach MIG definitions
Objective C/C++ headers
Also included with the main script (
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
gatherheaderdoc script also uses a tool called
resolveLinks to create links between documents. Although you probably won’t need to use this tool directly, you can do so if you need to link together multiple sets of documentation. This tool is described in Using resolveLinks to Resolve Cross References.
HeaderDoc comes with a series of tools for man page generation,
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
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.
How Do I Get It?
HeaderDoc is available in two ways. First, HeaderDoc is part of the standard 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/.
Organization of This Document
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
gatherheaderdocto 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.