Tags for C Headers

[Overview]

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

###

##