|< Previous PageNext Page >|
HeaderDoc comments are of the form:
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 tagging 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 “C Pseudoclass Tags”.
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:
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:
You can also use leading asterisks on each line of a multiline comment:
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:
will be formatted as two paragraphs in the HTML output:
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.
|< Previous PageNext Page >|
© 1999, 2004 Apple Computer, Inc. All Rights Reserved. (Last updated: 2004-10-27)