Using HeaderDoc

HeaderDoc includes two scripts, headerDoc2HTML.pl, which generates documentation for each header it encounters, and gatherHeaderDoc.pl, which finds these islands of documentation and assembles a master table of contents linking them together.

GatherHeaderDoc 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 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.pl”—information about running headerDoc2HTML.pl.
“Running gatherHeaderDoc.pl”—information about running gatherHeaderDoc.pl.
“Cocoa Front End”—information about the Cocoa front end.

Running headerDoc2HTML.pl

Once you have a header containing HeaderDoc comments, you can run the headerDoc2HTML.pl 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.

A Note About Objective-C Categories: An Objective-C category lets you add methods to an existing class. When HeaderDoc processes a batch of headers and finds comments for methods declared in a category, it searches for the associated class documentation and adds those methods and their documentation to the class documentation. If the class is not present in the current batch, HeaderDoc will create a separate frameset of documentation for the category.

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 @typedef, @function, and other C tags to document these declarations.

Note: The @method tag will generate faulty markup if the enclosing class does not have HeaderDoc markup. If this occurs, you will receive a warning that says that the @method tag is being used outside a class. To correct this, add a HeaderDoc comment for the enclosing class.

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.

Flag

Description

-C

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.

-D

Cause HeaderDoc to emit a Doxygen-style tag file.

-E

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.

-F

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 “Errata” for more info and patches.

-H

Turns on inclusion of the htmlHeader line, as specified in the configuration file.

-M

Specifies the section number to use when generating man page content with the -m flag.

-N

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.

-O

Enables “outer name only” type handling, in which tag names for typedefs are not documented (for example, foo in typedef struct foo {...} tdname;).

-P

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.

-Q

The opposite of quiet, this flag enables paranoid warnings about a number of common problems.

-S

Causes HeaderDoc to include functions and data types from the superclass in the documentation of child classes (if they are processed at once).

-T

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

-X

Causes HeaderDoc to output XML content instead of HTML.

-a

Tells HeaderDoc to attempt to align function parameters vertically after the opening parenthesis instead of indenting them by a single tab width.

-b

Puts HeaderDoc into “basic” mode. In this mode, numbered lists are not automatically recognized, and embedded headerdoc comments are not removed from declarations.

-c

Allows you to add an alternate configuration file. For example:

headerdoc2html -c myCustomHeaderDocConfigFile.config MyHeader.h

-d

Turns on extra debugging output.

-e

Specifies an exclude list. The file passed as an argument to the -e flag contains a newline-separated list of Perl regular expresssions. Any filename or file path that matches any of these regular expressions is excluded from processing.

-f

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.

-g

Group content on the right side by group instead of alphabetically.

-h

Causes HeaderDoc to output an XML file containing metadata about the HeaderDoc output.

-i

Tells HeaderDoc to output the body of macro declarations.

-j

Enables support for JavaDoc (/**) comment markers in other programming languages.

-l

Tells HeaderDoc not to generate link requests in declarations.

-m

Tells HeaderDoc to generate a man page for each function found in lieu of generating XML or HTML output.

-n

Ignore the names of classes and headers specified in HeaderDoc tags and always use the names provided by the code itself.

-o

Allows you to specify another directory for the output. For example:

headerdoc2html -o /tmp MyHeader.h

-p

Enables the C preprocessor. With this switch, any #define with HeaderDoc markup affects any content that appears after it within the same header file, and also affects any content after the #include in any file that includes that header file.

-q

Makes HeaderDoc operate silently (except for warnings and errors).

-s

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.

-t

Enables strict tagging mode, in which any function parameters not described with an @param tag result in a warning.

-u

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 @group or @functiongroup tags instead.

-v

Tells HeaderDoc to print version information and exit.

Most of these switches can be used in combination with each other. The obvious exceptions are -X and -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 hdxml2manxml and xml2man to convert the XML output to a man page yourself.

Running gatherHeaderDoc.pl

The gatherHeaderDoc.pl 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

This time, gatherHeaderDoc created the file OutputDir/MYTOCNAME.html instead of OutputDir/masterTOC.html.

For more information on configuring gatherHeaderDoc, see “Basic HeaderDoc Configuration.”

Cocoa Front End

Kyle Hammond has made a Cocoa front end available for HeaderDoc. Mac OS X users can download this from http://kyle.snowmintcs.com/cocoa_programming.php.

Last updated: 2009-11-17

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.