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.
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.
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.
|
|
|
Fields |
| @class | The name of the class. |
|
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:
| @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 | external resources that this class depends on (including classes, files, and so on) |
| @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 ths 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:
|
For member functions, use the @function tag (described in Tags for C Headers) or the @method tag (which behaves identically).
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:
|
|
|
Fields |
| @var | The name of the data member followed by the description. |
|
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.
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.
|
|
|
Fields |
| @templatefield | The name of the parameter followed by the description. |
|
Example
/*! @template mystackclass
@templatefield T the data type stored in this stack */
template <T> class mystackclass