< 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:
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.
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:
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:
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.
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-05-27)