---

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

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.

---