[Overview]

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 C Headers.

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.

 

Conventions

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

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

The tags highlighted in RED below are required.

 

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
{
...
}

 

Function Tags

For member functions, use the @function tag (described in Tags for C Headers) or the @method tag (which behaves identically).

 

Var Tags

For member data, you have two choices for tagging. You can use the type-specific tags described in Tags for C Headers if you want, or you can use the non-specific tag, @var:

Tag
Identifies
Fields
@var The name of the data member followed by the description.
2

Example

/*! @var we_are_root 		TRUE if this device is the root power domain */
bool we_are_root;

In general, it is better to use the type-specific tag if possible (however, not all types have tags), since the tag name gives HeaderDoc a hint about how to process the declaration that follows a comment. For example, the @struct tags lets HeaderDoc know that the declaration to follow may contain a set of curly braces containing lines ending in semicolons. If the same data member were tagged @var, HeaderDoc might be tempted to stop scanning for the declaration after the first semicolon (which would be appropriate in the we_are_root declaration above).

The @var tag is most appropriate for simple types like int, float, double, etc.

 

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.

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

Example

/*! @template		mystackclass
    @templatefield	T	the data type stored in this stack */
template <T> class mystackclass

 


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