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.

< Previous PageNext Page >