HeaderDoc Tags

Tags, depending on type, generally require either one field of information or two:

• @function [FunctionName]

• @param [parameterName] [Some descriptive text...]

In the tables in this chapter, the “Fields” column indicates the number of textual fields each type of tag takes.

Introduction to HeaderDoc Comments and Tags

HeaderDoc comments are of the form:

/*!

 This is a comment about FunctionName.

*/

char *FunctionName(int k);

In their simplest form (as above) they differ from standard C comments only by the addition of the ! character next to the opening asterisk.

In shell scripts or Perl scripts, the syntax is slightly altered because of the lack of multi-line comments and the need to avoid conflicting with the shell magic (#!) syntax. Shell script and Perl script HeaderDoc comments look like this:

# /*!

#     This is a comment about FunctionName.

#  */

sub FunctionName($$)

...

Historically, HeaderDoc tags were required to begin with an introductory tag that announces the type of API being commented (@function, below). You can find a complete list of these tags in “Top-Level HeaderDoc Tags.” Beginning in HeaderDoc 8, these top-level tags became optional. However, providing these tags can, in some cases, be used to cause HeaderDoc to document something in a different way. One example of this is the use of the @class tag to modify the markup of a typedef, as described in “Overriding the Default Data Type: C Pseudoclass Tags.”

The following example shows the historical syntax:

/*!

 @function FunctionName

 This is a comment about FunctionName.

*/

char *FunctionName(int k);

Following the optional top-level @function tag, you typically provide introductory information about the purpose of the class. You can divide this material into a summary sentence and in-depth discussion (using the @abstract and @discussion tags), or you can provided the material as an untagged block of text, as the examples below illustrate. You can also add @throws tags to indicate that the class throws exceptions or add an @namespace tag to indicate the namespace in which the class resides.

Listing 2-1  Example of documentation with @abstract and @discussion tags

/*!

 @class IOCommandGate

 @abstract Single-threaded work-loop client request mechanism.

 @discussion An IOCommandGate instance is an extremely light weight mechanism that

 executes an action on the driver's work-loop...

 @throws foo_exception

 @throws bar_exception

 @namespace I/O Kit (this is just a string)

 @updated 2003-03-15

*/

class IOCommandGate: public IOEventSource

{

...

}

Listing 2-2  Example of documentation as a single block of text

/*!

 @class IOCommandGate

 A class that defines a single-threaded work-loop client request mechanism. An IOCommandGate

 instance is an extremely light weight mechanism that executes an action on the driver's work-loop...

 @abstract Single-threaded work-loop client request mechanism.

 @throws foo_exception

 @throws bar_exception

 @updated 2003-03-15

*/

class IOCommandGate: public IOEventSource

{

...

}

You can also 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 balloon.

 @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). This tag is optional. If you leave it out, HeaderDoc will pick up this information from the declaration immediately following the comment.

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 that 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. */

You can also 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 newline characters 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.

 *

 * Always check the help balloon size before display.

 */

will be formatted as two paragraphs in the HTML output:

HMBalloonRect

OSErr HMBalloonRect (const HMMessageRecord *inMessage, Rect *outRect);

Use HMBalloonRect to get information about the size of a help balloon before the Help Manager displays it.

Always check the help balloon size before display.

Multiword Names

Top-level HeaderDoc tags, such as @header and @function can take multiword 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 multiword name or a name followed by a discussion.

There are two ways to get a multiword name. One way is to add a discussion tag, like this:

Listing 2-3  Example of multiword names using @discussion

 /*!

 * @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".

 */

The other way is to simply add a line break after the name.

Listing 2-4  Example of multiword names using multiple lines

 /*!

 * @enum example enum

 * This is a test, this is only a test.

 *

 * Because the discussion contains multiple lines, the name of the enum is

 * "example enum".

 */

Automatic Tagging

Beginning in HeaderDoc 8, certain tags are often not needed. These include:

Numbered lists

It is no longer necessary to mark up numbered lists with <ol><li>. HeaderDoc will automatically detect numbered lists.

Declaration types

Declaration type tags such as @function, @class, and @typedef are no longer required unless you are trying to override HeaderDoc’s normal behavior (such as using @class or @interface to change the display of a typedef struct.

Availability macros

It is no longer necessary to ignore availability macros with @ignore. The file Availability.list in the HeaderDoc modules directory contains a mapping of availability macros to strings. When any macros described in this file appear in a declaration, the corresponding text will automatically be added to its documentation as an availability attribute.

You can add your own availability macros by adding them to the Availability.list file or by adding an @availabilitymacro block in your headers.

Specifying Information About Frameworks

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

Specifying Information About an Entire Header or Source File

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.

In general, however, you will not specify a filename in the @header tag, and will simply let HeaderDoc substitute the filename. Note that you must follow @header by a line break; otherwise, the first line of your documentation will be treated as if it were the name of the header.

Listing 2-5  Example of @header tag

/*!

 @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"

*/

Additional HeaderDoc Tags

To enhance readability of this document, the tags are organized into groups by tag level. In HeaderDoc, there are two levels of tagging: top level tags and second level tags.

Top level tags must appear at the beginning of a HeaderDoc comment. These tags represent declaration types. For example, the @function tag tells HeaderDoc that you are about to declare a function. These tags are optional.

In most cases, second level tags can appear anywhere in a HeaderDoc comment. The one exception is the @constant tag because it conflicts with a top level tag. These tags give HeaderDoc additional information about the declaration, such as specifying an abstract or a parameter description.

Top-Level HeaderDoc Tags

Top-level HeaderDoc tags tell HeaderDoc what API type to expect after the declaration. These trace their roots back to HeaderDoc 7 and prior releases in which HeaderDoc could not interpret a declaration without these hints.

In HeaderDoc 8 and later, top level tags are always optional. Some of these tags provide useful features, however, such as availability macro declarations, API element groupings, and framework-level and header-level documentation.

Most top-level HeaderDoc tags are treated as a term and definition list. This means that if you specify multiple words on a single line, the first will be treated as the name, and the remaining words will be treated as the discussion. However, if the arguments span multiple lines, the entire first line will be treated as a multi-word title. Similarly, if you specify an @discussion tag explicitly, the entire line will be treated as a multi-word title. For more information, see “Multiword Names.”

A few top-level HeaderDoc tags do not support a discussion section. These tags automatically treat the remainder of the line as a multi-word name. These tags are: @functiongroup, @group, @methodgroup

Examples of Top-Level Tags and Type-Specific Second-Level Tags

Availability Macro Tags

Listing 2-6  Example of @availabilitymacro tag

/*!

 @availabilitymacro AVAILABLE_IN_MYAPP_1_0_AND_LATER This function is available in version 1.0 and later of MYAPP.

*/

This is usually followed by a #define or similar, but that is not necessary. This HeaderDoc comment is a standalone comment—that is, it does not cause the code after it to be processed in any way. If you want to mark a #define as being an availability macro, you should follow this tag with a second HeaderDoc comment for the #define itself.

Class Tags

Here are some examples of classes in different languages:

Listing 2-7  Example of @class tag in C++

/*!

 @class myClass

 @discussion This is a discussion.

 It can span many lines or paragraphs.

*/

 class myClass : public mySuperClass;

Listing 2-8  Example of @class tag in Objective-C

/*!

 @class myInterface

 @discussion This is a discussion.

 It can span many lines or paragraphs.

*/

@interface myInterface : NSObject

@end

Listing 2-9  Example of @protocol tag in Objective-C

/*!

 @protocol myProtocol

 @discussion This is a discussion.

 It can span many lines or paragraphs.

*/

@protocol myProtocol

@end

Listing 2-10  Example of @category tag in Objective-C

/*!

 @category myCategory(myMainClass)

 @discussion This is a discussion.

 It can span many lines or paragraphs.

*/

@interface myCategory(myMainClass)

@end

Classes have many special tags associated with them for convenience. These include:

The tag types are described in more detail in “Second Level HeaderDoc Tags.”

Tags for C++ Classes

Within a C++ class declaration, HeaderDoc allows some additional tags, as describe below.

Additional Tags for C++ Class Declarations

Within a C++ class comment, HeaderDoc understands all the tags for C header comments. It also adds the @templatefield tag.

For C++ template classes, if you want to document the template type parameters, you should use the @templatefield tag. You should also be sure to define the class using @template instead of @class.

The @templatefield tag can also be used to document template parameters for C++ template functions.

Listing 2-11  Example of @templatefield tag

/*! @class mystackclass

 @templatefield Tthe data type stored in this stack */

 template <T> class mystackclass

For more usage examples, see the ExampleHeaders folder that accompanies the HeaderDoc distribution.

Constant Tags

Listing 2-12  Example of @const tag

 /*!

 @const kCFTypeArrayCallBacks

 @abstract Predefined CFArrayCallBacks structure containing a set of callbacks appropriate...

 @discussion Extended discussion goes here.

 Lorem ipsum....

 */

 const CFArrayCallBacks kCFTypeArrayCallBacks;

#define Tags

Listing 2-13  Example of @defined tag

 /*!

 @defined TRUE

 @abstract Defines the boolean true value.

 @parseOnly

 @discussion Extended discussion goes here.

 Lorem ipsum....

 */

 #define TRUE 1

For more usage examples, see the ExampleHeaders folder that accompanies the HeaderDoc distribution.

Enum Tags

Listing 2-14  Example of @enum tag

/*!

 @enum Beverage Categories

 @abstract Categorizes beverages into groups of similar types.

 @constant kSoda Sweet, carbonated, non-alcoholic beverages.

 @constant kBeer Light, grain-based, alcoholic beverages.

 @constant kMilk Dairy beverages.

 @constant kWater Unflavored, non-sweet, non-caloric, non-alcoholic beverages.

 @discussion Extended discussion goes here.

 Lorem ipsum....

*/

enum {

 kSoda = (1 << 6),

 kBeer = (1 << 7),

 kMilk = (1 << 8),

 kWater = (1 << 9)

}

Function and Method Tags

For C functions, use the @function tag. For methods declared in an Objective-C class, protocol, or category, use the @method tag. For C++ methods, you can use either tag.

Listing 2-15  Example of @function tag

/*!

 @function ConstructBLT

 @abstract Creates a Sandwich structure from the supplied arguments.

 @param b Top ingredient, typically protein-rich.

 @param l Middle ingredient.

 @param t Bottom ingredient, controls tartness.

 @param mayo A flag controlling addition of condiment. Use YES for condiment,

 HOLDTHE otherwise.

 @throws peanuts

 @templatefield K The type of BLT to be generated (I want a BLT float)

 @result A pointer to a Sandwich structure. Caller is responsible for

 disposing of this structure.

 @discussion Extended discussion goes here.

 Lorem ipsum....

*/

Sandwich *ConstructBLT<K>(Ingredient b, Ingredient l, Ingredient t, Boolean mayo);

Listing 2-16  Example of @method tag

/*!

 @method dateWithString:calendarFormat:

 @abstract Creates and returns a calendar date initialized with the date

 specified in the string description.

 @discussion [An extended description of the method...]

 @param description A string specifying the date.

 @param format Conversion specifiers similar to those used in strftime().

 @result Returns the newly initialized date object or nil on error.

*/

+ (id)dateWithString:(NSString *)description calendarFormat:(NSString *)format;

For more usage examples, see the ExampleHeaders folder that accompanies the HeaderDoc distribution.

Grouping Tags

Listing 2-17  Example of @functiongroup tag

/*!

 @functiongroup Core Functions

*/

/*!

 @methodgroup Core Methods

*/

/*!

 @group Core API

*/

API groups are not required, but they allow you to organize a large number of functions into near groupings. Grouping tags remain in effect until the next grouping tag of the same type.

The @group tag provides grouping for all API elements except for methods and functions. In addition, until HeaderDoc encounters the @functiongroup or @methodgroup tag, functions and methods are also grouped by @group tag. In effect, the @functiongroup or @methodgroup tag provides a way to override the @group tag in a way that only affects functions and methods.

If you need to put functions or other API elements in different parts of the header into the same group, simply give them the same name (with the same capitalization, punctuation, spacing, etc.), and it will merge the two function groups into one.

Any functions or other API elements encountered before the first @group or @functiongroup are considered part of the “empty” group. These functions will be listed before any grouped functions or API elements.

Struct and Union Tags

Listing 2-18  Example of @struct tag

/*!

 @struct TableOrigin

 @abstract Locates lower-left corner of table in screen coordinates.

 @field x Point on horizontal axis.

 @field y Point on vertical axis

 @discussion Extended discussion goes here.

 Lorem ipsum....

*/

struct TableOrigin {

 int x;

 int y;

}

Typedef Tags

The tags that can appear after a “@typedef” tag depend on the type that you are defining, and are inherited from the valid tags for that enclosed type. The tags can include any of the following:

• @field for typedef struct declarations

• @constant for typedef enum declarations

• @param for simple typedef declarations of individual function pointer types

• @callback, @param, and @result for typedef struct declarations containing function pointers as members

Listing 2-19  Typedef for a simple struct

/*!

 @typedef TypedefdSimpleStruct

 @abstract Abstract for this API.

 @field firstField Description of first field

 @field secondField Description of second field

 @discussion Discussion that applies to the entire typedef'd simple struct.

 Lorem ipsum....

*/

typedef struct _structTag {

 short firstField;

 unsigned long secondField

} TypedefdSimpleStruct;

Listing 2-20  Typedef for an enumeration

/*!

 @typedef TypedefdEnum

 @abstract Abstract for this API.

 @constant kCFCompareLessThan Description of first constant.

 @constant kCFCompareEqualTo Description of second constant.

 @constant kCFCompareGreaterThan Description of third constant.

 @discussion Discussion that applies to the entire typedef'd enum.

 Lorem ipsum....

*/

typedef enum {

 kCFCompareLessThan = -1,

 kCFCompareEqualTo = 0,

 kCFCompareGreaterThan = 1

} TypedefdEnum;

Listing 2-21  Typedef for a simple function pointer

/*!

 @typedef simpleCallback

 @abstract Abstract for this API.

 @param inFirstParameter Description of the callback's first parameter.

 @param outSecondParameter Description of the callback's second parameter.

 @result Returns what it can when it is possible to do so.

 @discussion Discussion that applies to the entire callback.

 Lorem ipsum...

*/

typedef long (*simpleCallback)(short inFirstParameter, unsigned long long *outSecondParameter);

Listing 2-22  Typedef for a struct containing function pointers

/*! @typedef TypedefdStructWithCallbacks

 @abstract Abstract for this API.

 @discussion Defines the basic interface for Command DescriptorBlock (CDB) commands.

 @field firstField Description of first field.

 @callback setPointers Specifies the location of the data buffer. The setPointers function has the following parameters:

 @param cmd A pointer to the CDB command interface.

 @param sgList A pointer to a scatter/gather list.

 @result An IOReturn structure which returns the return value in the structure returned.

 @field lastField Description of the struct's last field.

*/

typedef struct _someTag {

 short firstField;

 IOReturn (*setPointers)(void *cmd, IOVirtualRange *sgList);

 unsigned long lastField

} TypedefdStructWithCallbacks;

Variable Tags

The @var tag should be used when marking up global variables, class variables, and instance variables (as opposed to actual declaration of new data types).

Listing 2-23  Example of @var tag

/*! @var we_are_root

    @abstract Tells whether this device is the root power domain

    @discussion TRUE if this device is the root power domain.

    For more information on power domains....

 */

 bool we_are_root;

Second Level HeaderDoc Tags

The tags in the table below (except as noted)) can be used in any comment for any data type, function, header, or class.

The different types of tags are:

• attribute—The contents of this tag will appear as an attribute in a list of attributes. These should generally be short, but like block tags, attribute tags continue until the next block or attribute tag.

• block—The contents of this tag can contain multiple paragraphs of text.

• HTML tagging—The contents of this tag affect HTML tagging and are not displayed.

• inline—This tag can appear within a paragraph in most other tags (but not in name or title fields). The contents of an inline tag do not break the text flow.

• page footer—This tag modifies contents in the footer at the bottom of each content page.

• parsing—This tag modifies the way the source code file is parsed.

In addition, some attribute tags are labeled as “term & definition” style. This means that they behave just like top level tags in terms of their format. This format is described in “Multiword Names.”

Overriding the Default Data Type: C Pseudoclass Tags

There are three tags provided for C pseudoclasses, such as COM interfaces. The @class tag is used for generic pseudoclasses. The @interface tag is used for COM interfaces. The @superclass tag can be added to an @class or @interface declaration to modify its behavior.

You should mark up any C pseudoclasses in the same way you would mark up a C++ class. Apart from the unusual form of function declarations (in the form of function pointers), the resulting output should be similar to that of a C++ class.

The @superclass tag can be used when you have a superclass-like relationship between two C pseudoclasses or COM interfaces. Using this tag will cause the documentation for the specified pseudo-superclass to be injected into the documentation for the current pseudoclass.

The primary purpose for this feature is to reduce the amount of bloat in headers, allowing you to document function pointers in the top level pseudoclass and then only document the additional function pointers in pseudoclasses that expand upon them.

Listing 2-24  Example of @class tag

/*!

 @class IOFireWireDeviceInterface_t

 @superclass IOFireWireDevice

*/

 typedef struct IOFireWireDeviceInterface_t

{

    IUNKNOWN_C_GUTS;

.

.

.

}

The @class tag causes the typedef structthat follows the HeaderDoc comment to be treated as a class. This is a frequently-used technique in kernel programming. A slight variation of this tag, @interface, is provided for COM interfaces so that they can be identified as such in the TOC. An example of this tag follows:

Listing 2-25  Example of @interface tag

/*!

 @interface IOFireWireDeviceInterface_t

 @superclass IOFireWireDevice

*/

 typedef struct IOFireWireDeviceInterface_t

{

    IUNKNOWN_C_GUTS;

.

.

.

}

Unknown Tag Handling

To avoid warnings and unexpected output, if you need to use an at sign (@) outside the scope of a HeaderDoc tag, you should quote it by preceding it with a backslash. For example:

/*! @header

        For more information, contact myemail\@myaddress.top.

 */

If you do not quote the at sign, it will be treated as the start of a tag name, and you may get unexpected behavior.

Beginning in HeaderDoc 8.6 and later, a warning is generated when an unknown tag is encountered, and the tag is converted into text.

Prior to version 8.6, unknown tags were partially removed. The initial at sign (@) was deleted, leaving only the content following it.