Important: This document may not represent best practices for current development. Links to downloads and other resources may no longer be valid.
HeaderDoc includes two scripts,
headerDoc2HTML.pl in the source distribution), which generates documentation for each header it encounters, and
gatherHeaderDoc.pl in the source distribution), which finds these islands of documentation and assembles a master table of contents linking them together.
gatherheaderdoc tool is a postprocessing script for HeaderDoc. Its primary purpose is to take a directory containing output from HeaderDoc and create a table of contents with links.
gatherheaderdoc tool is highly configurable. You can configure it to insert custom breadcrumb links, use a custom TOC template, and even automatically insert “framework” information into the TOC template, if desired.
This chapter is divided into three parts:
Running headerdoc2html—information about running
Running gatherheaderdoc—information about running
Once you have a header containing HeaderDoc comments, you can run the
headerdoc2html script to generate HTML output like this:
> headerdoc2html MyHeader.h
This will process
MyHeader.h and create an output directory called
MyHeader in the same directory as the input file. To view the results in your web browser, open the file
index.html that you find inside the output directory.
Instead of specifying a single input file (as above), you can specify an input directory if you wish. HeaderDoc will process every
.h file in the input directory (and all of its subdirectories), generating an output directory of HTML files for each header that contains HeaderDoc comments.
HeaderDoc and Object-Oriented Languages
HeaderDoc processes C++ and Objective-C headers in much the same way that it does a C header. In fact, until HeaderDoc encounters a class declaration in a C++ header, the processing is identical.
When HeaderDoc generates the HTML documentation for a C++ or Objective-C header, it creates one frameset for the header as a whole, and separate framesets for each class, protocol, or category declared within the header.
Within Objective-C class declarations, you can use the
@method tag to document each method. Since Objective-C is a superset of C, the header might also declare types, functions, or other API outside of any class declaration. You would use
@function, and other C tags to document these declarations.
HeaderDoc records the access control level (public, protected, or private) of API elements declared within a C++ class. This information is used to further group the API elements in the resulting documentation.
HeaderDoc Command-line Switches
HeaderDoc has a number of useful command-line switches that alter its behavior.
Causes HeaderDoc to output class contents as a composite page instead of breaking it up into separate pages for functions, data types, and so on.
Specifies that the token should be explicitly defined to the specified value (or 1 if no value is specified) for C preprocessing purposes.
Process everything. With this flag, HeaderDoc attempts to process an entire file, including content that has no HeaderDoc markup.
Note: Not all programming languages support this flag.
Tells HeaderDoc to generate framesets instead of using iframe elements.
Note: In HeaderDoc 8.7, you should generally specify this flag because of a problem with links opening in a new page in the iframe-based output. See Late-Breaking Bugs for more info and patches.
Turns on inclusion of the
Disables emission of documentation for function-local variables (documented with the
Specifies the section number to use when generating man page content with the
Ignore all names specified in HeaderDoc tags (except for anonymous enums in which no name is provided by the code) and use the names specified by the code instead.
Enables “outer name only” type handling, in which tag names for typedefs are not documented (for example,
Pipe mode. In this mode, HeaderDoc prints the resulting XML content (default) or function list to standard output. You can only process a single file at a time in this mode.
The opposite of quiet, this flag enables paranoid warnings about a number of common problems.
Causes HeaderDoc to include functions and data types from the superclass in the documentation of child classes (if they are processed at once).
HeaderDoc test mode. Note that this test mode is only available when running from a source tarball, not from the installed system. For more information, see Testing HeaderDoc.
Specifies that the token should be explicitly undefined for C preprocessing purposes.
Causes HeaderDoc to output XML content instead of HTML.
Tells HeaderDoc to attempt to align function parameters vertically after the opening parenthesis instead of indenting them by a single tab width.
Puts HeaderDoc into “basic” mode. In this mode, numbered lists are not automatically recognized, and embedded HeaderDoc comments are not removed from declarations.
Allows you to add an alternate configuration file. For example:
Turns on extra debugging output.
Specifies an exclude list. The file passed as an argument to the
Enables function list output mode. In this mode, HeaderDoc emits a simple list of function names encountered and the contents of those functions in an easily machine-parseable format.
Group content on the right side by group instead of alphabetically.
Tells HeaderDoc to output the body of macro declarations.
Enables support for JavaDoc (
Tells HeaderDoc not to generate link requests in declarations.
Tells HeaderDoc to generate a man page for each function found in lieu of generating XML or HTML output.
Ignore the names of classes and headers specified in HeaderDoc tags and always use the names provided by the code itself.
Allows you to specify another directory for the output. For example:
Enables the C preprocessor. With this switch, any
Makes HeaderDoc operate silently (except for warnings and errors).
Causes HeaderDoc to enter a comment stripping mode, in which it outputs a copy of your header file in the output directory from which all HeaderDoc comments have been removed.
Enables strict tagging mode, in which any function parameters not described with an
Disables sorting of functions, data types, and so on in the table of contents, thus preserving the original file order. Note that if you simply want to preserve groupings, you should use the
Tells HeaderDoc to print version information and exit.
Causes HeaderDoc to emit a Doxygen-style tag file. (Note that this variant of the tag file format adds class inheritance information that is not typically included in a normal Doxygen tag file.)
Sets the format used for the table of contents (left side). Valid values are:
Enables various flags and additional policy checks specific to Apple internal use.
Include documentation marked with
Most of these switches can be used in combination with each other. The obvious exceptions are
-m (XML vs. man page output). If you need both XML and man page output, you should specify the
-X flag (XML output), then run the scripts
xml2man to convert the XML output to a man page yourself.
gatherheaderdoc script scans an input directory (recursively) for any documentation generated by
headerdoc2html. It creates a master table of contents (named
masterTOC.html by default—the name can be changed by setting a new name in the configuration file or by specifying a second argument). It also adds a “top” link to all the documentation sets it visits to make it easier to navigate back to the master table of contents.
Here's an example of how to create documentation for a number of headers (the sample ones provided with the scripts) and then generate a master table of contents:
> headerdoc2html -o OutputDir ExampleHeaders
> gatherheaderdoc OutputDir
You can now open the file
OutputDir/masterTOC.html in your browser to see the interlinked sets of documentation.
You can also add a second argument to change the output file name. For example:
> headerdoc2html -o OutputDir ExampleHeaders
> gatherheaderdoc OutputDir MYTOCNAME.html
gatherheaderdoc created the file
OutputDir/MYTOCNAME.html instead of
For more information on configuring
gatherheaderdoc, see Basic HeaderDoc Configuration.