Tags for C Headers

• Conventions
• Tags Common to All API Types
• Function Tags
• struct and union Tags
• enum tags
• typedef tags
• #define tags

Conventions

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.

The tags highlighted in RED below are required.

Tags Common to All API Types

The @abstract and @discussion tags can be used within any of the type-specific tags below. For example,:

/*!
  @enum Beverage Categories
  @abstract Constants to group beverage types.
  @discussion These constants (such as kSoda, kBeer, etc.) can be used...
*/

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.

Function Tags

Tag	Identifies	Fields
@function	The name of the function.	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

Example:

/*! 
  @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;
);

Struct and Union Tags

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

Example:

/*!
  @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;
}

Enum Tags

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

Example:

/*!
  @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)
}

Typedef Tags

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. If the new type is a synonym for a structure, then @field tags are used. If the new type is a function pointer (a callback), the @param tags are used.

Example 1 - Typedef for a struct:

/*!
  @typedef Sandwich
  @discussion Defined type used by functions in the Repast Manager.
  @field upper Bread for upper surface.
  @field top First ingredient, from top to bottom.
  @field middle Second ingredient, from top to bottom.
  @field bottom Third ingredient, from top to bottom.
  @field other Additional, optional, ingredient. 
  @field upper Bread for lower surface.
  */
typedef struct sandwich {
    Bread upper;
    Ingredient top;
    Ingredient middle;
    Ingredient bottom;
    Ingredient other;
    Bread lower;
} Sandwich;

Example 2 - Typedef for a function pointer:

/*!
     @typedef Action
     @discussion Type and arguments of callout C function that is used when ...
     @param owner Target of the function; can be used as a refcon. 
     @param arg0 Argument to action from run operation.
     @param arg1 Argument to action from run operation.
     @param arg2 Argument to action from run operation.
     @param arg3 Argument to action from run operation.
*/
     typedef IOReturn (*Action)(OSObject *owner,
                                void *arg0, void *arg1,
                                void *arg2, void *arg3);
		

#define Tags

Tag	Identifies	Fields
@defined	Name of the symbolic constant.	1

Example:

  /*!
    @defined TRUE
    @discussion Defines the boolean true value.
  */
  #define TRUE 1