HeaderDoc is a system for embedding structured commentary in C and C++ header files and producing rich HTML output from that commentary. 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's behavior.
In addition to traditional HeaderDoc markup, HeaderDoc 8 supports JavaDoc markup. HeaderDoc 8 also supports a number of additional languages: Bourne shell, C Headers, C source code, C shell, C++ headers, Java, JavaScript, Mach MIG definitions, Objective C/C++ headers, Pascal, Perl, PHP. Most of these languages (besides C/C++/ObjC/Pascal) only support documenting functions or subroutines.
A simple HeaderDoc comment for a function might look like this:
/*!
@function HMBalloonRect
@discussion Use HMBalloonRect to get information about the size of a help balloon before the
Help Manager displays it.
@param inMessage The help message for the help balloon.
@param outRect The coordinates of the rectangle that encloses the help message. The upper-left
corner of the rectangle has the coordinates (0,0).
*/
OSErr HMBalloonRect (const HMMessageRecord *inMessage, Rect *outRect);
When converted to HTML (by headerDoc2HTML, described below), the tagged comment above produces this output:
HMBalloonRect
Use HMBalloonRect to get information about the size of a help balloon before the Help Manager displays it. Parameters
|
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 the next section.
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.
Once you have a header containing HeaderDoc comments, you can run the headerDoc2HTML.pl script to generate HTML output like this:
> headerDoc2HTML.pl 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.
If you want to specify another directory for the output, use the "-o" switch:
> headerDoc2HTML.pl -o /tmp MyHeader.h
HeaderDoc normally lists the name of each file it processes to the Terminal. The "-q" switch makes HeaderDoc operate silently:
> headerDoc2HTML.pl -q MyHeader.h
> headerDoc2HTML.pl -qo /tmp MyHeader.h
The "-H" switch turns on inclusion of the htmlHeader line, as specified in the config file.
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 "-X" switch causes HeaderDoc to output XML content instead of HTML.
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 "-d" switch turns on extra debugging output.
The "-h" switch causes HeaderDoc to output an XML file containing metadata about the HeaderDoc output.
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" switch disables sorting of functions, data types, and so on.
You can use the "-v" switch to make HeaderDoc report the versions of all its constituent modules. This can be useful for bug reporting purposes.
> headerDoc2HTML.pl -v
This 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.pl -o OutputDir ExampleHeaders > gatherHeaderDoc.pl 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.pl -o OutputDir ExampleHeaders > gatherHeaderDoc.pl OutputDir MYTOCNAME.html
This time, gatherHeaderDoc created the file OutputDir/MYTOCNAME.html instead of OutputDir/MasterTOC.html.
For more information on configuring gatherHeaderDoc and on modifying the default TOC template, see The Configuration File.
Kyle Hammond has made a Cocoa front end available for HeaderDoc. Mac OS X users can download this from their website at http://www.isd.net/dsl03002/CocoaProgramming.html.
You can set values for some commonly altered variables. Currently, the configuration file lets you set these things:
- copyrightOwner
- The copyright notice that appears at the bottom of the HTML pages. Unless you specify a value, no copyright will appear.
- defaultFrameName
- The name of the file containing the frameset instructions (by default, index.html).
- compositePageName
- The name of the file containing the printable HTML page (by default, CompositePage.html).
- masterTOCName
- The name of the file containing the master table of contents for a series of headers (by default, MasterTOC.html). (This variable is used by the gatherHeaderDoc script, and can be overridden on the command line.)
- apiUIDPrefix
- The prefix for named anchors in the HTML (by default, apple_ref). (In the HTML, HeaderDoc adds a self-describing named anchor near each API declaration -- for example <a name="//apple_ref/c/func/CFArrayAppendValue">. These can be useful for index generation and other purposes. See Symbol Markers for HTML-based Documentation for more information.)
- ignorePrefixes
- A list of tokens to leave out of the final output if they occur at the start of a line (before any other non-whitespace characters).
- htmlHeader
- A string (generally a server-side include directive) that HeaderDoc will insert into the top of each right-side and composite HTML page if you specify the -H flag on the command line. For longer headers, use htmlHeaderFile.
- htmlHeaderFile
- A file containing longer HTML headers. The contents of this file will be added to each content page if you specify the -H flag on the command line.
- dateFormat
- A string specifying the date format to be used by HeaderDoc. A few valid examples include Y/M/D, M-D-Y, M/Y, Y.
- ignorePrefixes
- Specifies a list of tokens to remove from HeaderDoc markup. Generally used to remove debug macros.
- HeaderDoc Styles:
These contain CSS formatting for various parts of declarations. For example:
funcNameStyle => background:#ffffff; color:#000000;
- commentStyle
- style for comments
- preprocessorStyle
- style for preprocessor directives
- funcNameStyle
- style for function names
- stringStyle
- style for strings
- charStyle
- style for characters ('a')
- numberStyle
- style for numbers
- keywordStyle
- style for keywords
- typeStyle
- style for data types
- paramStyle
- style for function parameters
- varStyle
- style for variable names
- useBreadCrumbs
Controls whether HeaderDoc will insert breadcrumb links into content pages instead of adding [Top] in the TOC. Valid Values are 0 or 1.
The path leading up to the current framework must be included manually in the htmlHeader or htmlHeaderFile directive. The breadcrumb is inserted wherever
<!-- begin breadcrumb --><!-- end breadcrumb -->appears in the htmlHeader or htmlHeaderFile content.
- TOCTemplateFile
- Specifies a TOC template file to use instead of the built-in TOC template. For more information, see Creating a TOC Template File.
HeaderDoc looks in three places for values for these variables, in this order:
A variable can be assigned a value in any of these places, but only the last value read for a given variable will affect the output of a run of the script. If you are happy with the default values for these variables (as described above), you don't need to provide a configuration file. If you want to change just one or more values, provide a configuration file that declares just those values.
The format of the configuration file is this:
key1 => value1
key2 => value2
Here is a sample configuration file.
TOC template files are basically ordinary HTML files. They can contain any HTML content. In addition to HTML content, they can also contain conditional HTML content---that is, content that is only included if certain conditions are met. Finally, they can include various lists.
The template support is particularly powerful when combined with support for frameworks (which, for HeaderDoc's purposes, is essentially a loose grouping of related documentation stored in the same output directory).
Below are the special tags that indicate conditional or list content:
- $$title@@
- Inserts "Foo Documentation" where Foo is the framework name.
- $$framework@@
- Inserts the framework name.
- $$frameworkdiscussion@@
- Inserts the framework discussion
- $$frameworkabstract@@
- Inserts the framework abstract
- $$headersection@@
- Start of conditional block for headers. If there are no headers listed, content prior to the closing conditional block tag will not appear.
- $$/headersection@@
- End of conditional block for headers.
- $$headerlist@@
- A list of all headers in the output directory.
- $$classsection@@
- Start of conditional block for classes. If there are no classes listed, content prior to the closing conditional block tag will not appear.
- $$/classsection@@
- End of conditional block for classes.
- $$classlist@@
- A list of all classes in the output directory.
- $$categorysection@@
- Start of conditional block for categories. If there are no categories listed, content prior to the closing conditional block tag will not appear.
- $$/categorysection@@
- End of conditional block for categories.
- $$categorylist@@
- A list of all categories in the output directory.
- $$protocolsection@@
- Start of conditional block for protocols. If there are no protocols listed, content prior to the closing conditional block tag will not appear.
- $$/protocolsection@@
- End of conditional block for protocols.
- $$protocollist@@
- A list of all protocols in the output directory.
- $$datasection@@
- Start of conditional block for data (globals and constants). If there are no data elements listed, content prior to the closing conditional block tag will not appear.
- $$/datasection@@
- End of conditional block for data (globals and constants).
- $$datalist@@
- A list of all data elements in the output directory.
- $$typesection@@
- Start of conditional block for types. If there are no types listed, content prior to the closing conditional block tag will not appear.
- $$/typesection@@
- End of conditional block for types.
- $$typelist@@
- A list of all types in the output directory.
- $$functionsection@@
- Start of conditional block for functions/methods. If there are no functions/methods listed, content prior to the closing conditional block tag will not appear.
- $$/functionsection@@
- End of conditional block for functions/methods.
- $$functionlist@@
- A list of all functions/methods in the output directory.
List tags default to a raw list (single column) with no border. However, you can change the number of columns, the table width, and border quite easily. For example:
$$functionlist cols=3 order=down atts=border="0" cellpadding="1" cellspacing="0" width="420"@@
specifies that the table will be three columns, listed down the first column, then down the next column, and so on. It also specifies that the additional attributes border, cellpadding, cellspacing, and width will be inserted into the table tag automatically. Note that the atts parameter must be the last parameter listed.
HeaderDoc comments are of the form:
/*!
@function FunctionName
This is a comment about FunctionName.
*/
In their simplest form (as above) they differ from standard C comments in only two ways:
However, you can use additional JavaDoc-like tags within the HeaderDoc comment to identify specific fields of information. These tags will make the comments more amenable to conversion to HTML. For example, a more complete comment might look like this:
/*!
@function HMBalloonRect
@abstract Reports size and location of help ballon.
@discussion Use HMBalloonRect to get information about the size of a help balloon
before the Help Manager displays it.
@param inMessage The help message for the help balloon.
@param outRect The coordinates of the rectangle that encloses the help message.
The upper-left corner of the rectangle has the coordinates (0,0).
*/
Tags are indicated by the "@" character, which must generally appear as the first non-whitespace character on a line (with a few notable exceptions). If you need to include an at sign in the output (to put your email address in a class discussion, for example), you can do this by prefixing it with a backslash, that is "\@".
The first tag in a comment announces the API type of the declaration (function, struct, enum, and so on). The next two lines (tagged @abstract and @discussion) provide documentation about the API element as a whole. The abstract can be used in summary lists, and the discussion can be used in the detailed documentation about the API element.
The abstract and discussion tags are optional, but encouraged. Their use enables various improvements in the HTML output, such as summary pages. However, if there is untagged text following the API type tag and name (@function HMBalloonRect, above) it is assumed to be a discussion. With such untagged text, HeaderDoc assumes the discussion extends from the end of the API-type comment to the next HeaderDoc tag or to the end of the HeaderDoc comment, whichever occurs first.
HeaderDoc understands some variants in commenting style. In particular, you can have a one-line comment like this:
/*! @var settle_time Latency before next read. */
...and you can use leading asterisks on each line of a multiline comment:
/*! * @function HMBalloonRect * @abstract Reports size and location of help ballon. * @discussion Use HMBalloonRect to get information about the size of a help balloon * before the Help Manager displays it. * @param inMessage The help message for the help balloon. * @param outRect The coordinates of the rectangle that encloses the help message. * The upper-left corner of the rectangle has the coordinates (0,0). */
If you want to specify a line break in the HTML version of a comment, use two carriage returns between lines rather than one. For example, the text of the discussion in this comment:
/*! * @function HMBalloonRect * @discussion Use HMBalloonRect to get information about the size of a help balloon * before the Help Manager displays it. * * By checking the help balloon size before display, you can guard against... */
...will be formatted as two paragraphs in the HTML output:
HMBalloonRect
Use HMBalloonRect to get information about the size of a help balloon before the Help Manager displays it. By checking the help balloon size before display, you can guard against...
|
Top level HeaderDoc tags, such as "@header" and "@function" can generally take multi-word names. This is particularly useful for documenting anonymous types for enumerations, for example. However, HeaderDoc normally has no way to know whether a line containing multiple words is a multi-word name or a name followed by a discussion.
To get a multi-word name, you must therefore add a discussion tag, like this:
/*! * @enum example enum * @discussion This is a test, this is only a test. * * Because we included an \@discussion tag, the name of the enum is * "example enum". */
Framework documentation should be inserted into a file ending in .hdoc. Running HeaderDoc on this file generates a documentation tree with special hidden markup that gatherHeaderDoc will insert into the appropriate place within your TOC template (or at the top of the built-in template).
|
|
|
|
|
|---|---|---|---|
| @framework | @framework Kernel Framework | The name of the framework. |
|
| @abstract | @abstract In-kernel device driver framework | A short string that briefly describes a framework. This should not contain multiple lines (at least for the default template) for aesthetic reasons. Save the detailed descriptions for the discussion tag. |
|
| @discussion | @discussion The kernel framework contains functions useful to in-kernel device drivers. | A detailed description of the framework. This may contain multiple paragraphs, and can contain HTML markup. |
|
Often, you'll want to add a comment for the header as a whole in addition to comments for individual API elements. For example, if the header declares API for a specific manager (in Mac OS terminology), you may want to provide introductory information about the manager or discuss issues that apply to many of the functions within the manager's API. Likewise, if the header declares a C++ class, you could discuss the class in relation to its superclass or subclasses.
The value you give for the @header tag serves as the title for the HTML pages generated by headerDoc2HTML. The text you associate with the @header tag is used for the introductory page of the HTML website the script produces.
The tags in the table below (with the exception of @header, which must be at the start of a comment block) can be used in any comment for any data type, function, header, or class.
|
|
|
|
|
|---|---|---|---|
| @abstract | @abstract write the track to disk | A short string that briefly describes a function, data type, and so on. This should not contain multiple lines (because it will look odd in the mini-TOCs). Save the detailed descriptions for the discussion tag. |
|
| @availability | @availability 10.3 and later | A string that describes the availability of a function, class, and so on. |
|
| @copyright | @copyright Apple | Copyright info to be added to each page. This overrides the config file value and may not span multiple lines. |
|
| @deprecated | @deprecated in version 10.4 | String telling when the function, data type, etc. was deprecated. |
|
| @discussion | @discussion . . @some_other_tag |
A block of text that describes a function, class, header, or data type in detail. This may contain multiple paragraphs. @discussion may be omitted, as described above. @discussion must be present if you have a multi-word name for a data type, function, class, or header. |
|
| @header | @header Repast Manager | The name under which the API is categorized. Typically used to declare the Manager name (for classic Mac APIs) or class name (for object-oriented APIs) The following subtags are available:
Explanation of types:
|
|
| @link | @link apple_ref//c/func/function_name link text goes here @/link or @link function_name link text goes here @/link |
Allows you to insert a link request for an api ref. If the link target is part of the same .h file, you can do this by using only the name of the function or data type. If it is in a separate file (or if there are multiple matches for a given name), you must explicitly specify which api ref to use. This tag is an inline-compatible tag. |
|
| @meta | @meta robots index,nofollow or @meta http-equiv="refresh" content="0;http://www.apple.com" |
Meta tag info to be added to each page. This can be either in the form "@meta <name> <content>" or "@meta <complete tag contents>", and may not span multiple lines. |
|
| @namespace | @namespace BSD Kernel | String describing the namespace in which the function, data type, etc. exists. |
|
| @textblock | @textblock . . @/textblock |
Treat everything until the trailing @/textblock as raw text, preserving initial spaces and line breaks, and converting "<" and ">" to "<" and ">". Note that this tag does not automatically insert <pre> or <tt>. You may wrap it with whatever formatting you choose. This tag is an inline-compatible tag. |
|
| @updated | @updated 2003-03-14 | The date at which the header was last updated. |
|
| @version | @version 2.3.1 | the version number to which this documentation applies |
|
Example:
/*! @header Repast Manager The Repast Manager provides a functional interface to the repast driver. Use the functions declared here to generate, distribute, and consume meals. @copyright Dave's Burger Palace @updated 2003-03-14 @meta http-equiv="refresh" content="0;http://www.apple.com" */
Tags are largely specific to a particular programming language—the @method tag has no place in a C header, for example. Refer to the following sections for information about which tags are available for a particular language context.