HeaderDoc Unfettered: Tags for C++ Headers

## Tags for C++ Headers

HeaderDoc processes a C++ header in much the same way that it does a C header. In fact, until HeaderDoc encounters a class declaration in a C++ header, the processing is identical. This means you can use any of the tags defined for C headers within a C++ header. See “Tags for All Languages”.

For example, in a header that declares two classes, you may want to use the @header tag to provide a discussion explaining why these classes are grouped, and use the @class tags to provide discussions for each of the classes.

Once HeaderDoc encounters an @class tag (with accompanying class declaration) in a C++ header, it treats all comments and declarations that follow (until the end of the class declaration) as belonging to that class, rather than to the header as a whole. When HeaderDoc generates the HTML documentation for a C++ header, it creates one frameset for the header as a whole, and separate framesets for each class declared within the header.

HeaderDoc records the access control level (public, protected, or private) of API elements declared within a C++ class. This information is used to group the API elements in the resulting documentation.

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

#### In this section:

> Conventions
> Additional Tags for C++ Class Declarations

### Conventions

Tags, depending on type, can introduce either one or two fields of information:

- @function [FunctionName]
- @param [parameterName] [Some descriptive text...]

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

### Additional Tags for C++ Class Declarations

Within a C++ class declaration, HeaderDoc understands all the Tags for C Headers, along with some new ones which are listed in the following sections.

#### Class Tags

Tag | Identifies | Fields
@class | The name of the class. | 1

Following the @class 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.

Example 1 - Documentation tagged as abstract and discussion:

    /*!
| `
`
     @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
| `
`
    {
| `
`
    ...
| `
`
    }
| `
`

Example 2 - Documentation as 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...
| `
`
     @throws foo_exception
| `
`
     @throws bar_exception
| `
`
     @updated 2003-03-15
| `
`
    */
| `
`
    class IOCommandGate: public IOEventSource
| `
`
    {
| `
`
    ...
| `
`
    }
| `
`

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

Tag | Disposition
--- | ---
@classdesign | BLOCK: description of any common design considerations that apply to this class, such as consistent ways of handling locking or threading
@coclass | TERM/DEFINITION: class with which this class was designed to work
@dependency | STRING: external resource that this class depends on (such as a class or file)
@helper or @helperclass | TERM/DEFINITION: helper classes used by this class
@helps | STRING: if this is a helper class, short description of classes that this class was designed to help
@instancesize | STRING: the size of each instance of the class
@ownership | BLOCK: description of ownership model to which this class conforms, e.g. MyClass objects are owned by the MyCreatorClass object that created them
@performance | BLOCK: description of this class's special performance characteristics, e.g. this class is optimized for the Velocity Engine, or this class is strongly discouraged in high-performance contexts
@security | BLOCK: security considerations associated with the use of this class
@superclass | STRING: override superclass name---see note below.

Explanation of types:

- STRING: single string, like @abstract
- TERM/DEFINITION: <name> <description>, like @enum
- BLOCK: block of text like @discussion

Note: The @superclass tag is not generally required for superclass information to be included. The @superclass tag has two purposes:

- to add "superclass" info to a C pseudo-classes such as a COM interface (a `typedef struct` containing function pointers).
- to enable inclusion of superclass functions, types, etc. in the subclass docs. The superclass MUST be processed before the subclass (earlier on the command line or higher up in the same file), or this may not work correctly.

#### Function Tags

For member functions, use the @function tag (described in “Function Tags”) or the @method tag (which behaves identically for C++ methods).

#### Template Tags

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.

Tag | Identifies | Fields
--- | --- | ---
@templatefield | The name of the parameter followed by the description. | 2

Example

    /*! @templatemystackclass
| `
`
     @templatefieldTthe data type stored in this stack */
| `
`
| `
`
     template <T> class mystackclass
| `
`
| `
`

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

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