Introduction to HeaderDoc Comments and Tags

HeaderDoc comments in C and C-like languages (Java, JavaScript, IDL, PHP, and MIG) 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 AppleScript and Pascal, the syntax is almost identical except for the comment markers:

Listing 2-1  AppleScript comment example

(*! This is a comment about FunctionName. *)

on FunctionName(x,y)

    ...

end FunctionName

Listing 2-2  Pascal comment example

{! This is a comment about FunctionName. }

procedure FunctionName(a, b: String; j: Integer): Char;

begin

    ...

end;

In Perl, Tcl, and shell 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:

Listing 2-3  Perl comment example

# /*!

#     This is a comment about FunctionName.

#  */

sub FunctionName($$)

{

    ...

}

Listing 2-4  Shell comment example

# /*!

#     This is a comment about FunctionName.

#  */

FunctionName()

{

    ...

}

Similarly, Ruby and Python syntax do not lend themselves to a start-of-comment marker followed by a single exclamation point, so their comments look like this:

Listing 2-5  Ruby comment example

=begin

    !headerDoc!

    This is a comment about FunctionName.

=end

def FunctionName(arg)

    ...

end

Listing 2-6  Python comment example

"""

    !headerdoc!

    This is a comment about FunctionName.

"""

def FunctionName(x):

   ...

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 Groups of Declarations. 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-7  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-8  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, \@. (If you forget the backslash, to the extent that it is possible to do so, HeaderDoc ignores unknown tags and treats them as though you had quoted the @ characters, but it does produce a warning. Because new tags are periodically added, you should not count on this behavior.)

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

Be sure, however, to understand the difference between the above syntax and the following, which is treated as a multiword name (described in Multiword Names):

/*! @enum my favorite enumeration

    This is the discussion here.

 */

You can also use leading asterisks on each line of a multiline comment (but you must use them consistently):

/*!

 * @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:

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 an explicit discussion tag (which may be empty), like this:

Listing 2-9  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 and additional discussion (which may not be empty) after the name.

Listing 2-10  Example of multiword names using multiple lines

/*!

 * @enum example enum

 * Because the discussion continues on a second line,

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

Types of Tags

HeaderDoc tags can be grouped into two broad categories: top-level tags and second-level tags. Top-level tags describe the type of declaration that follows. For example, @method indicates that the following declaration is a method. All other tags are second-level tags.

HeaderDoc Tags Common to All Comment Types

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

In addition, HeaderDoc supports some common JavaDoc and Doxygen synonyms for other tags: @since (@availability), @details (@discussion), and @description (@discussion)

HeaderDoc Comment Types

HeaderDoc handles comments differently based on the declaration that follows them. Although most tags are valid in any HeaderDoc comment, there are a few tags that only make sense in certain contexts. For example, a method can have parameters, but a class cannot.

This section describes each type of HeaderDoc comment, and provides a list of second-level tags that are specific to that comment type.

/*! @framework Kernel Framework Reference

    @abstract

    @discussion The Kernel Framework provides the APIs and support for

    kernel-resident device drivers and other kernel extensions.

    It defines the base class for I/O Kit device drivers (IOService),

    several helper classes, and the families supporting many types

    of devices.

    @frameworkpath /System/Library/Frameworks/Kernel.framework

    @frameworkuid TP30000816

    @seealso //apple_ref/doc/uid/TP0000011 I/O Kit Fundamentals

    @seealso //apple_ref/doc/uid/TP30000905-CH204 Kernel Programming

 */

/*!

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

 */

/*!

     @class myInterface

     @discussion This is a discussion.

     It can span many lines or paragraphs.

*/

@interface myInterface : NSObject

@end

/*!

     @protocol myProtocol

     @discussion This is a discussion.

     It can span many lines or paragraphs.

*/

@protocol myProtocol

@end

/*!

 @category myMainClass(myCategory)

 @discussion This is a discussion.

 It can span many lines or paragraphs.

*/

@interface myMainClass(myCategory)

@end

/*!

 @class myClass

 @discussion This is a discussion.

 It can span many lines or paragraphs.

*/

 class myClass : public mySuperClass;

/*! @class mystackclass

    @templatefield Tthe data type stored in this stack */

 template <T> class mystackclass

/*!

 @functiongroup Core Functions

*/

/*!

 @methodgroup Core Methods

*/

/*!

 @group Core API

*/

/*!

    This is a function.

    @param parmA

        Parameter A.

    @param parmB

        Parameter B.

    @result

        Returns something unexpected.

 */

SpanishInquisition *myFunction(char *parmA, int parmB);

/*!

    This is an objective-C method.

    @param parmA

        Parameter A.

    @param parmB

        Parameter B.

    @result

        Results in global warming.

 */

- (CO2 *)doSomething:(typeName)parmA withSomething:(typeName)parmB;

 /*!

     @const kCFTypeArrayCallBacks

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

     @discussion Extended discussion goes here.

         Lorem ipsum....

 */

const CFArrayCallBacks kCFTypeArrayCallBacks;

/*!

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

/*!

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

}

/*!

     @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 beverages {

 kSoda = (1 << 6),

 kBeer = (1 << 7),

 kMilk = (1 << 8),

 kWater = (1 << 9)

};

/*!

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

};

/*!

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

/*!

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

/*!

     @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);

/*!

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

 /*!

     @defined TRUE

     @abstract Defines the boolean true value.

     @parseOnly

     @discussion Extended discussion goes here.

         Lorem ipsum....

 */

 #define TRUE 1

 /*!

     @definedblock Colors of the rainbow

     @abstract Defines some RGB colors.

     @discussion Extended discussion goes here.

         Lorem ipsum....

     @define kInfrared The color infrared.

     @define kRed The color red.

     @define kOrange The color orange.

     @define kYellow The color yellow.

     @define kGreen The color green.

     @define kCyan The color cyan.

     @define kBlue The color blue.

     @define kViolet The color violet.

     @define kUltraviolet The color ultraviolet.

 */

 #define kInfrared "#000000"

 #define kRed "#FF0000"

 #define kOrange "#FF8000"

 #define kYellow "#FFFF00"

 #define kGreen "#00FF00"

 #define kCyan "#00FFFF"

 #define kBlue "#0000FF"

 #define kViolet "#FF00FF"

 #define kUltraviolet "#000000"

/*! @/definedblock */

/*!

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

*/

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-32  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-33  Example of @interface tag

/*!

 @interface IOFireWireDeviceInterface_t

 @superclass IOFireWireDevice

*/

 typedef struct IOFireWireDeviceInterface_t

{

    IUNKNOWN_C_GUTS;

.

.

.

}

Creating Links Between Symbols

As mentioned in Adding Arbitrary Attributes, there are three ways you can use the @link tag:

@link function_name @/link

or

@link function_name link text goes here @/link

or

@link //apple_ref/c/func/function_name link text goes here @/link

Beginning in HeaderDoc 8.7, you can link to any symbol by its name. (In previous versions of HeaderDoc, you can link to symbols by name if the link target is part of the same .h file or in any file processed before it in the same processing run.)

If there are multiple matches for a given name (or if you are using a pre-8.7 version of HeaderDoc and the symbol is parsed afterwards), you may need to explicitly specify which symbol to use. (See Resolving Conflicting API References to learn about symbol matching precedence.) To avoid the conflict, you include an API reference marker for the symbol instead of its name. For some C++ methods, you may also need to tweak the reference marker so that it does not look like a C-style end-of-comment token. See Using API References in the @link Tag for details.

Because the headerdoc2html script does not know the actual target for these links, it inserts special link request comments into the output. You must then run gatherheaderdoc or resolveLinks to actually turn those comments into working links.

See Using resolveLinks to Resolve Cross References to learn more about the resolving process and the various options available to you.

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.

Adding Arbitrary Attributes

In addition to predefined attributes such as @author, @coclass, @security, and so on, HeaderDoc also supports the ability to add your own custom attributes by using the following tags:

• @attribute

• @attributeblock

• @attributelist

The first tag, @attribute, is straightforward:

@attribute My Attribute Name

    Value goes here.

This tag is intended for short attributes. When this tag is used in HeaderDoc comments that describe API elements whose documentation provides a separate metadata table (classes and headers, for example), these attributes appear in that metadata table. In comments for other API elements, these attributes appear after the discussion.

The syntax for the second tag, @attributeblock, is the same as @attribute. The difference is that @attributeblock is intended for longer blocks of content (potentially containing multiple paragraphs instead of just a few words). Attributes tagged with @attributeblock always appear after the discussion.

The final tag, @attributelist, is intended for attributes containing very basic term-and-definition lists. For example:

@attributelist List name goes here

    Term Defintion goes here.

    Term2 Definition goes here.

These lists appear in the metadata table for the related API element, if applicable. Otherwise, they appear after the discussion. The use of @attributelist tags in HeaderDoc comments that describe API elements whose documentation provides a metadata table is discouraged for readability reasons.