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:

• AppleScript

• Bourne shell (and Korn and Bourne Again)

• C Headers and C source code

• C++ headers

• C shell scripts

• Java

• JavaScript

• Mach MIG definitions

• Objective C/C++ headers

• Pascal

• Perl

• Python

• PHP

• Ruby

• Tcl

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.

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