Introduction

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:

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.

The 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, 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.

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.