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.

Historically, HeaderDoc tags also required the addition of a tag that announces the type of API being commented (“@function”, below). Beginning in HeaderDoc 8, this tag became optional.

/*!

 @function FunctionName

 This is a comment about FunctionName.

*/

char *FunctionName(int k);

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 to modify the markup of a typedef, as described in “C Pseudoclass Tags”.

/*!

 @class ClassName

 This is a comment about ClassName.

*/

typedef struct foo {...};

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 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_timeLatency 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

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.

By checking the help balloon size before display, you can guard against...

© 1999, 2004 Apple Computer, Inc. All Rights Reserved. (Last updated: 2004-05-27)