< Previous PageNext Page >


C Pseudoclass Tags

There are three tags provided for C pseudoclasses, such as COM interfaces. The @class tag is used for generic pseudoclasses. The @interface tag is used for COM interfaces. The @superclass tag can be added to an @class or @interface declaration to modify its behavior.

In this section:

Class Tags
Interface Tags
Superclass Tags

Class Tags


Tag

Identifies

Fields

@class

The name of the class.

1


Listing 2-16 Example of @class tag

/*! 
 @class IOFireWireDeviceInterface_t
*/
 typedef struct IOFireWireDeviceInterface_t
{
    IUNKNOWN_C_GUTS;
.
.
.
}

The @class tag causes the typedef struct that follows the HeaderDoc comment to be treated as a class. This is a frequently-used technique in kernel programming. A slight variation of this tag, @interface, is provided for COM interfaces so that they can be identified as such in the TOC.

You should mark up any C pseudoclasses in the same way you would mark up a C++ class. Apart from the unusual form of function declarations (in the form of function pointers), the resulting output should be similar to that of a C++ class.


Interface Tags


Tag

Identifies

Fields

@interface

The name of a COM interface.

1


Listing 2-17 Example of @interface tag

/*! 
 @interface IOFireWireDeviceInterface_t
*/
 typedef struct IOFireWireDeviceInterface_t
{
    IUNKNOWN_C_GUTS;
.
.
.
}

The @class tag causes the typedef struct that follows the headerdoc comment to be treated as a COM interface (which is essentially a C pseudoclass with a different name).

You should mark up any C pseudoclasses in the same way you would mark up a C++ class. Apart from the unusual form of function declarations (in the form of function pointers), the resulting output should be similar to that of a C++ class.


Superclass Tags


Tag

Identifies

Fields

@superclass

The name of the superclass.

1


Listing 2-18 Example of @superclass tag

/*! 
 @class IOFireWireDeviceInterface_t
 @superclass IOFireWireDevice
*/
 typedef struct IOFireWireDeviceInterface_t
{
    IUNKNOWN_C_GUTS;
.
.
.
}

The @superclass tag can be used when you have a superclass-like relationship between two C pseudoclasses or COM interfaces. Using this tag will cause the documentation for the specified pseudo-superclass to be injected into the documentation for the current pseudoclass.

The primary purpose for this feature is to reduce the amount of bloat in headers, allowing you to document function pointers in the top level pseudoclass and then only document the additional function pointers in pseudoclasses that expand upon them.

Note that in order for this feature to work, both pseudoclasses must be processed at the same time.



< Previous PageNext Page >


© 1999, 2004 Apple Computer, Inc. All Rights Reserved. (Last updated: 2004-05-27)