Tags for C++ Headers

• Conventions
• Additional Tags for C++ Class Declarations
  • Class Tags
  • Var Tags

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:

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

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.

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...  
*/
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...  
*/
class IOCommandGate : public IOEventSource
{
...
}

Function Tags

For member functions, use the @function tag (described in Tags for C Headers).

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