<html> <head> <meta http-equiv="content-type" content="text/html;charset=iso-8859-1"> <title>Tags for C Headers</title> </head> <body bgcolor="white"> <a href="HeaderDoc.html">[Overview]</a> <h1>Tags for C Headers</h1> <ul> <li><a href="#Anchor-Conventions-34807">Conventions</a> <li><a href="#Anchor-Conventions-34807">Tags Common to All API Types</a> <li><a href="#Anchor-Class">Class Tags</a> <li><a href="#Anchor-Groups">Function Group Tags</a> <li><a href="#Anchor-Function-59404">Function Tags</a> <li><a href="#Anchor-Struct-38219">struct and union Tags</a> <li><a href="#Anchor-Enum-54325">enum tags</a> <li><a href="#Anchor-Typedef-58500">typedef tags</a> <li><a href="#constTag">const tags</a> <li><a href="#Anchor-42424">#define tags</a> </ul> <h2> </h2> <h2><a name="Anchor-Conventions-34807"></a>Conventions</h2> <p>Tags, depending on type, can introduce either one or two fields of information:</p> <ul> <p><tt>@function [FunctionName]</tt><tt><br> @param [parameterName] [Some descriptive text...]</tt></p> </ul> <p>In the tables below, the "Fields" column indicates the number of textual fields each type of tag takes.</p> <p>The tags highlighted in <font size="4" color="#660000"><b>RED</b></font> below are required.</p> <p> </p> <h2><a name="Anchor-Tags-30189"></a>Tags Common to All API Types</h2> <p>The <b>@abstract</b>, <b>@updated</b>, and <b>@discussion</b> tags can be used within any of the type-specific tags below. For example,:</p> <pre>/*! @enum Beverage Categories @abstract Constants to group beverage types. @discussion These constants (such as kSoda, kBeer, etc.) can be used... @updated 2003-04-15 */</pre> <p>They are not required within any HeaderDoc comment, but can improve the formatting of the HTML output, and can help automate the importation of comments into the Inside Mac documentation database.</p> <p> </p> <h2><a name="Anchor-Class"></a>Class Tags</H2> <p> <table border="1" cellpadding="0" cellspacing="2" width="92%"> <tr> <td> <center> <b>Tag</b></center> </td> <td> <center> <b>Identifies</b></center> </td> <td><b>Fields</b></td> </tr> <tr> <td><font color="#660000"><b>@class</b></font></td> <td>The name of the class.</td> <td> <center> 1</center> </td> </tr> </table> </p> <p><b>Example:</b></p> <pre>/*! @class IOFireWireDeviceInterface_t */ typedef struct IOFireWireDeviceInterface_t { IUNKNOWN_C_GUTS ; . . . } </pre> <p> The <b>@class</b> tag causes the <tt>typedef struct</tt> that follows the headerdoc comment to be treated as a class. This is commonly used for COM interfaces, but is also a frequently-used technique in kernel programming.</p> <p> You should mark up any C pseudoclasses in the same way as 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.</p> <p> <p> <h2><a name="Anchor-Groups"></a>Function Group Tags</H2> <p> <table border="1" cellpadding="0" cellspacing="2" width="92%"> <tr> <td> <center> <b>Tag</b></center> </td> <td> <center> <b>Identifies</b></center> </td> <td><b>Fields</b></td> </tr> <tr> <td><font color="#660000"><b>@functiongroup</b></font></td> <td>The name of the function group.</td> <td> <center> 1</center> </td> </tr> </table> </p> <p><b>Example:</b></p> <pre>/*! @functiongroup Core Functions */ </pre> <p> Function groups are not required, but they allow you to organize a large number of functions into near groupings. The <b>@functiongroup</b> tag remains in effect until the next <b>@functiongroup</b> tag.<p> 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.<p> Note that functions encountered before the first <b>@functiongroup</b> are considered part of the "empty" group. These functions will be listed before any grouped functions. <p> <p> <h2><a name="Anchor-Function-59404"></a>Function Tags</h2> <p> <table border="1" cellpadding="0" cellspacing="2" width="92%"> <tr> <td> <center> <b>Tag</b></center> </td> <td> <center> <b>Identifies</b></center> </td> <td><b>Fields</b></td> </tr> <tr> <td><font color="#660000"><b>@function</b></font></td> <td>The name of the function.</td> <td> <center> 1</center> </td> </tr> <tr> <td><b>@param</b></td> <td>Each of the function's parameters.</td> <td> <center> 2</center> </td> </tr> <tr> <td><b>@result</b></td> <td>The return value of the function. Don't include if the return value is void or OSERR</td> <td> <center> 1</center> </td> </tr> </table> </p> <p><b>Example:</b></p> <pre>/*! @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. @result A pointer to a Sandwich structure. Caller is responsible for disposing of this structure. */ Sandwich *ConstructBLT(Ingredient b, Ingredient l, Ingredient t, Boolean mayo);</pre> <h2><a name="Anchor-Struct-38219"></a>Struct and Union Tags</h2> <p> <table border="1" cellpadding="0" cellspacing="2" width="92%"> <tr> <td> <center> <b>Tag</b></center> </td> <td> <center> <b>Identifies</b></center> </td> <td><b>Fields</b></td> </tr> <tr> <td><font color="#660000"><b>@struct </b></font><font color="#660000">/<b> @union</b></font></td> <td>The name of the structure or union. (Also known as the struct or union's tag.)</td> <td> <center> 1</center> </td> </tr> <tr> <td><b>@field</b></td> <td>A field in the structure.</td> <td> <center> 2</center> </td> </tr> </table> </p> <p><b>Example:</b></p> <pre>/*! @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; }</pre> <h2><a name="Anchor-Enum-54325"></a>Enum Tags</h2> <p> <table border="1" cellpadding="0" cellspacing="2" width="92%"> <tr> <td> <center> <b>Tag</b></center> </td> <td> <center> <b>Identifies</b></center> </td> <td><b>Fields</b></td> </tr> <tr> <td><font color="#660000"><b>@enum</b></font></td> <td>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.</td> <td> <center> 1</center> </td> </tr> <tr> <td><b>@constant</b></td> <td>A constant within the enumeration.</td> <td> <center> 2</center> </td> </tr> </table> </p> <p><b>Example:</b></p> <pre>/*! @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) }</pre> <h2><a name="Anchor-Typedef-58500"></a>Typedef Tags</h2> <p> <table border="1" cellpadding="0" cellspacing="2" width="92%"> <tr> <td> <center> <b>Tag</b></center> </td> <td> <center> <b>Identifies</b></center> </td> <td><b>Fields</b></td> </tr> <tr> <td><font color="#660000"><b>@typedef</b></font></td> <td>The name of the defined type.</td> <td> <center> 1</center> </td> </tr> <tr> <td><i><b>various</b></i></td> <td>The tags that can appear after a "@typedef" tag depend on the definition of the new type. <br><br> <b>@field</b> for typedef'd structs<br> <b>@constant</b> for typedef'd enumerations<br> <b>@param</b> for simple typedef'd function pointers<br> <b>@callback</b>, <b>@param</b>, <b>@result</b> for typedef'd structs containing function pointers<br> </td> <td></td> </tr> </table> </p> <p><b>Example 1 - Typedef for a simple struct:</b></p> <pre>/*! @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;</pre> <p> </p> <p><b>Example 2 - Typedef for an enumeration:</b></p> <pre>/*! @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;</pre> <p> </p> <p><b>Example 3 - Typedef for a simple function pointer:</b></p> <pre>/*! @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);</pre> <p> </p> <p><b>Example 4 - Typedef for a struct containing function pointers:</b></p> <pre>/*! @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;</pre> <p> </p> <h2><tt><a name="constTag"></a>const Tags</tt></h2> <p><tt> <table border="1" cellpadding="0" cellspacing="2" width="92%"> <tr> <td> <center> <b>Tag</b></center> </td> <td> <center> <b>Identifies</b></center> </td> <td><b>Fields</b></td> </tr> <tr> <td><font color="#660000"><b>@const</b></font></td> <td>Name of the constant.</td> <td> <center> 1</center> </td> </tr> </table> </tt></p> <p><tt><b>Example:</b> </tt></p> <pre> /*! @const kCFTypeArrayCallBacks @discussion Predefined CFArrayCallBacks structure containing a set of callbacks appropriate... */ const CFArrayCallBacks kCFTypeArrayCallBacks;</pre> <p> </p> <h2><tt><a name="Anchor-42424"></a>#define Tags</tt></h2> <p><tt> <table border="1" cellpadding="0" cellspacing="2" width="92%"> <tr> <td> <center> <b>Tag</b></center> </td> <td> <center> <b>Identifies</b></center> </td> <td><b>Fields</b></td> </tr> <tr> <td><font color="#660000"><b>@defined</b></font></td> <td>Name of the constant.</td> <td> <center> 1</center> </td> </tr> </table> </tt></p> <p><tt><b>Example:</b> </tt></p> <pre> /*! @defined TRUE @discussion Defines the boolean true value. */ #define TRUE 1 </pre> <p> <hr> <center> For more usage examples, see the <b>ExampleHeaders</b> folder that accompanies the HeaderDoc distribution. </center> </body> </html>