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 Command-line Switches

HeaderDoc has a number of useful command-line switches that alter its behavior.

The -C switch 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.

The -H switch turns on inclusion of the htmlHeader line, as specified in the configuration file.

The -M switch allows you to set the section number for man pages generated with -m. For example,

 > headerdoc2html -m -M 3 MyHeader.h

would generate man pages designed for section 3 of the manual. If the -m flag is not specified, this flag has no effect.

The -O switch enables “outer name only” type parsing, in which tag names for typedefs are not documented (for example, foo in typedef struct foo {...} tdname;).

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

The -X switch causes HeaderDoc to output XML content instead of HTML.

The -a switch enables column alignment in declarations.

The -b switch puts HeaderDoc into “basic” mode. In this mode, numbered lists are not automatically recognized, and embedded headerdoc comments are not removed from declarations.

The -c switch allows you to add an alternate configuration file. For example:

 > headerdoc2html -c myCustomHeaderDocConfigFile.config MyHeader.h

The -d switch turns on extra debugging output.

The -h switch causes HeaderDoc to output an XML file containing metadata about the HeaderDoc output.

The -i switch tells HeaderDoc to output the body of macro declarations.

The -l switch tells HeaderDoc not to generate link requests in declarations.

The -m switch tells HeaderDoc to generate a man page for each function found in lieu of generating XML or HTML output.

The -o switch allows you to specify another directory for the output. For example:

 > headerdoc2html -o /tmp MyHeader.h

The -p switch enables the C preprocessor. Any #define with HeaderDoc markup will affect any content that appears after it within the same header file, and will also affect any content after the #include in any file that includes that header file.

The -q switch makes HeaderDoc operate silently.

The -s switch 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.

The -t switch enables strict tagging mode, in which any function parameters not described with an @param tag result in a warning.

The -u (unsorted) switch 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.

The -v switch outputs version information.

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.