< Previous PageNext Page > |
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.
Conventions
Additional Tags for C++ Class Declarations
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.
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.
Table 2-15 :
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.
|
|
Classes have many special tags associated with them for convenience. These include:
Table 2-16 :
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.
For member functions, use the @function tag (described in “Function Tags”) or the @method tag (which behaves identically for C++ methods).
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.
Table 2-17 :
Tag |
Identifies |
Fields |
---|---|---|
@templatefield |
The name of the parameter followed by the description. |
2 |
|
For more usage examples, see the ExampleHeaders
folder
that accompanies the HeaderDoc distribution.
< Previous PageNext Page > |
© 1999, 2004 Apple Computer, Inc. All Rights Reserved. (Last updated: 2004-10-27)