Tags for All Languages
In this section:
Availability Macro Tags
Constant Tags
#define Tags
Enum Tags
Function Tags
Function Group Tags
Struct and Union Tags
Typedef Tags
Variable tags
Availability
Macro Tags
Table 2-3 :
Tag |
Identifies |
Fields |
@availabilitymacro |
The name of the availability macro and a string describing
it. If the macro name appears in the declaration of any later function,
class, method, or data type, the string will be added to its documentation
as an availability attribute. See “Automatic Tagging” for more
information. |
2 |
Listing 2-4 : Example
of @availabilitymacro tag
/*!
|
| @availabilitymacro AVAILABLE_IN_MYAPP_1_0_AND_LATER This function is available in version 1.0 and later of MYAPP.
|
| */
|
|
|
This is usually followed by a #define or similar, but that
is not necessary. This HeaderDoc comment is a standalone comment—that
is, it does not cause the code after it to be processed in any way.
If you want to mark a #define as
being an availability macro, you should follow this tag with a second
HeaderDoc comment for the #define itself.
Constant
Tags
Table 2-4 :
Tag |
Identifies |
Fields |
@const
or @constant |
Name of the constant. |
1 |
Listing 2-5 : Example
of @const tag
/*!
|
| @const kCFTypeArrayCallBacks
|
| @discussion Predefined CFArrayCallBacks structure containing a set of callbacks appropriate...
|
| */
|
| const CFArrayCallBacks kCFTypeArrayCallBacks;
|
|
|
#define
Tags
Table 2-5 :
Tag |
Identifies |
Fields |
@define or @defined |
Name of the macro. |
1 |
@parseOnly |
Marks macro as “hidden”. The macro will be parsed and
used by the C preprocessor, but will not be included as a separate #define entry
in the resulting documentation. |
1 |
Listing 2-6 : Example
of @defined tag
/*!
|
| @defined TRUE
|
| @discussion Defines the boolean true value.
|
| */
|
| #define TRUE 1
|
|
|
|
|
For more usage examples, see the ExampleHeaders
folder
that accompanies the HeaderDoc distribution.
Enum
Tags
Table 2-6 :
Tag |
Identifies |
Fields |
@enum |
The name of the enumeration. This is the enum's tag,
if it has one. Otherwise, supply a name you want to have the constants grouped
under in the documentation. |
1 |
@constant |
A constant within the enumeration. |
2 |
Listing 2-7 : Example
of @enum tag
/*!
|
| @enum Beverage Categories
|
| @discussion Categorizes beverages into groups of similar types.
|
| @constant kSoda Sweet, carbonated, non-alcoholic beverages.
|
| @constant kBeer Light, grain-based, alcoholic beverages.
|
| @constant kMilk Dairy beverages.
|
| @constant kWater Unflavored, non-sweet, non-caloric, non-alcoholic beverages.
|
| */
|
| enum {
|
| kSoda = (1 << 6),
|
| kBeer = (1 << 7),
|
| kMilk = (1 << 8),
|
| kWater = (1 << 9)
|
| }
|
|
|
Function Tags
Table 2-7 :
Tag |
Identifies |
Fields |
@function |
The name of the function or macro. |
1 |
@param |
Each of the function's parameters. |
2 |
@result |
The return value of the function. Don't include if the
return value is void or OSERR |
1 |
@throws |
Include one @throws tag
for each exception thrown by this function (in languages that support
exceptions). |
1 |
@templatefield |
Each of the function’s template fields (C++). |
2 |
Listing 2-8 : Example
of @function tag
/*!
|
| @function ConstructBLT
|
| @discussion Creates a Sandwich structure from the supplied arguments.
|
| @param b Top ingredient, typically protein-rich.
|
| @param l Middle ingredient.
|
| @param t Bottom ingredient, controls tartness.
|
| @param mayo A flag controlling addition of condiment. Use YES for condiment,
|
| HOLDTHE otherwise.
|
| @throws peanuts
|
| @templatefield K The type of BLT to be generated (I want a BLT float)
|
| @result A pointer to a Sandwich structure. Caller is responsible for
|
| disposing of this structure.
|
| */
|
| Sandwich *ConstructBLT<K>(Ingredient b, Ingredient l, Ingredient t, Boolean mayo);
|
|
|
Function
Group Tags
Table 2-8 :
Tag |
Identifies |
Fields |
@functiongroup |
The name of the function group. |
1 |
Listing 2-9 : Example
of @functiongroup tag
/*!
|
| @functiongroup Core Functions
|
| */
|
|
|
|
|
Function groups are not required, but they allow you to organize
a large number of functions into near groupings. The @functiongroup tag
remains in effect until the next @functiongroup tag.
If you need to put functions in different parts of the header
into the same group, simply give them the same name (with the same
capitalization, punctuation, spacing, etc.), and it will merge the
two function groups into one.
Note that functions encountered before the first @functiongroup are
considered part of the “empty” group. These functions will be
listed before any grouped functions.
Struct
and Union Tags
Table 2-9 :
Tag |
Identifies |
Fields |
@struct / @union |
The name of the structure or union. (Also known as the
struct or union's tag.) |
1 |
@field |
A field in the structure. |
2 |
Listing 2-10 : Example
of @struct tag
/*!
|
| @struct TableOrigin
|
| @discussion Locates lower-left corner of table in screen coordinates.
|
| @field x Point on horizontal axis.
|
| @field y Point on vertical axis
|
| */
|
| struct TableOrigin {
|
| int x;
|
| int y;
|
| }
|
|
|
Typedef
Tags
Table 2-10 :
Tag |
Identifies |
Fields |
@typedef |
The name of the defined type. |
1 |
various |
The tags that can appear after a “@typedef”
tag depend on the definition of the new type. @field for
typedef’d structs @constant for
typedef'd enumerations @param for
simple typedef'd function pointers @callback, @param, @result for
typedef'd structs containing function pointers |
|
Listing 2-11 : Typedef
for a simple struct
/*!
|
| @typedef TypedefdSimpleStruct
|
| @abstract Abstract for this API.
|
| @discussion Discussion that applies to the entire typedef'd simple struct.
|
| @field firstField Description of first field
|
| @field secondField Description of second field
|
| */
|
|
|
| typedef struct _structTag {
|
| short firstField;
|
| unsigned long secondField
|
| } TypedefdSimpleStruct;
|
|
|
Listing 2-12 : Typedef
for an enumeration
/*!
|
| @typedef TypedefdEnum
|
| @abstract Abstract for this API.
|
| @discussion Discussion that applies to the entire typedef'd enum.
|
| @constant kCFCompareLessThan Description of first constant.
|
| @constant kCFCompareEqualTo Description of second constant.
|
| @constant kCFCompareGreaterThan Description of third constant.
|
| */
|
| typedef enum {
|
| kCFCompareLessThan = -1,
|
| kCFCompareEqualTo = 0,
|
| kCFCompareGreaterThan = 1
|
| } TypedefdEnum;
|
|
|
Listing 2-13 : Typedef
for a simple function pointer
/*!
|
| @typedef simpleCallback
|
| @abstract Abstract for this API.
|
| @discussion Discussion that applies to the entire callback.
|
| @param inFirstParameter Description of the callback's first parameter.
|
| @param outSecondParameter Description of the callback's second parameter.
|
| @result Returns what it can when it is possible to do so.
|
| */
|
| typedef long (*simpleCallback)(short inFirstParameter, unsigned long long *outSecondParameter);
|
|
|
Listing 2-14 : Typedef
for a struct containing function pointers
/*! @typedef TypedefdStructWithCallbacks
|
| @abstract Abstract for this API.
|
| @discussion Defines the basic interface for Command DescriptorBlock (CDB) commands.
|
|
|
| @field firstField Description of first field.
|
|
|
| @callback setPointers Specifies the location of the data buffer. The setPointers function has the following parameters:
|
| @param cmd A pointer to the CDB command interface.
|
| @param sgList A pointer to a scatter/gather list.
|
| @result An IOReturn structure which returns the return value in the structure returned.
|
|
|
| @field lastField Description of the struct's last field.
|
| */
|
| typedef struct _someTag {
|
| short firstField;
|
| IOReturn (*setPointers)(void *cmd, IOVirtualRange *sgList);
|
| unsigned long lastField
|
| } TypedefdStructWithCallbacks;
|
|
|
Variable
tags
The @var tag should
be used when marking up global variables, class variables, and instance
variables (as opposed to actual declaration of new data types).
Table 2-11 :
Tag |
Identifies |
Fields |
@var |
The name of the data member followed by the description. |
2 |
Listing 2-15 : Example
of @var tag
/*! @var we_are_root TRUE if this device is the root power domain */
|
|
|
| boolwe_are_root;
|
|
|
© 1999, 2004 Apple Computer, Inc. All Rights Reserved. (Last updated: 2004-10-27)