--- title: Introduction framework: developertools role: article path: apple-archive/documentation/DeveloperTools/Conceptual/HeaderDoc/intro --- # Introduction Explains how to extract API reference documentation from commented header files. ## 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](../gatherheaderdoc/gatherheaderdoc.html#//apple_ref/doc/uid/TP40001215-CH350-BABDEHCI) . 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](../anchors/anchors.html#//apple_ref/doc/uid/TP40001215-CH347-SW11) . 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/](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](../usage/usage.html#//apple_ref/doc/uid/TP40001215-CH337-CDEBBJJA) explains the syntax for the HeaderDoc command-line tool itself. - [HeaderDoc Tags](../tags/tags.html#//apple_ref/doc/uid/TP40001215-CH346-CHDJFEGF) explains how to add HeaderDoc markup to header (and source code) files. - [Basic HeaderDoc Configuration](../config/config.html#//apple_ref/doc/uid/TP40001215-CH348-CEGJFJIB) explains the HeaderDoc configuration file. - [Advanced HeaderDoc Configuration and Features](../gatherheaderdoc/gatherheaderdoc.html#//apple_ref/doc/uid/TP40001215-CH350-BABDEHCI) explains how to use `gatherheaderdoc` to produce landing pages and cross-linked trees of related documentation. - [Using the MPGL Suite](../mpgl/mpgl.html#//apple_ref/doc/uid/TP40001215-CH357-CDEBBJJA) explains how to use the Manual Page Generation Language (MPGL) tool suite. - [HeaderDoc Release Notes](../releasenotes/releasenotes.html#//apple_ref/doc/uid/TP40001215-CH201-TPXREF101) provides recent version history for the HeaderDoc toolchain. - [Symbol Markers for HTML-Based Documentation](../anchors/anchors.html#//apple_ref/doc/uid/TP40001215-CH347-BABJIFFD) describes the symbol markers used by HeaderDoc and various other utilities to provide linking functionality. - [HeaderDoc Class Hierarchy](../classhierarchy/classhierarchy.html#//apple_ref/doc/uid/TP40001215-CH349-CHDGBFAJ) describes the class hierarchy of the HeaderDoc tool itself. - [Troubleshooting](../troubleshooting/troubleshooting.html#//apple_ref/doc/uid/TP40001215-CH366-SW1) explains common error messages and their likely causes. [Next](../usage/usage.html) Copyright © 1999, 2016 Apple Inc. All Rights Reserved. [Terms of Use](http://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](http://www.apple.com/privacy/) | Updated: 2016-05-05