Header Browser's Documentation : C/C++ tags

The @var tag take one argument : the name of the global variable. Type it exactly as the variable name, and mind to put this HeaderBrowser comment just before the variable declaration.
 * @var         homerBeer
 * @abstract    Current Homer's beer.
 * @discussion  Global pointer to the beer that Homer is
 *              drinking.
beer_t      *homerBeer;

/*! @var lisaSolo   Score of the Lisa's saxophone solo */
saxoScore   *lisaSolo;

The @function tag take one argument : the name of the function. Type it exactly as the function name, and mind to put this HeaderBrowser comment just before the function declaration. There is two tags that you could use in function tags.
@param: takes two arguments, the name of the parameter and a descriptive text relative to the parameter. You could type as many param tags as there is parameters in the function. Try to write the param tags in the same order than in function declaration.

@result (or @return for JavaDoc addicts): has just one argument, a text that identify the return value of the function. It is not necessary to put a result tag if the return type is void.

See this example :
 * @function    cookChicken
 * @abstract    Cook a chicken with the given sauce.
 * @discussion  This function take a chicken, draw it, prepare
 *              it with the wanted sauce, and roast it.
 * @param       weight    The weight of the chicken.
 * @param       sauce     The sauce for cooking. Could be a
 *                        NULL pointer.
 * @result      A pointer to the cooked chicken.
chicken_t	*cookChicken(int weight, spice_t sauce);

@field: takes two arguments, the name of the field and a descriptive text relative to this field. You could put as many field tags as there is fields in the structure.
 * @struct      chicken_s
 * @abstract    Contains all chicken's properties.
 * @discussion  All properties of chickens (weight, color, ...)
 *              are stored in this structure.
 * @field       color     Hexadecimal color value.
 * @field       weight    Weight of the chicken in kg.
 * @field       age       How old the chicken is.
struct       chicken_s {
    color_t  color;
    int      weight;
    int      age;

This tag is similar to the struct tag.
 * @union       character_u
 *              A movie character.
 * @field       cool      A Simpson's family person.
 * @field       brave     A Jedi knight.
 * @field       sexy      A baywatch actress.
union            character_u {
    simpson_t    *cool;
    jedi_t       *brave;
    falsy_t      *sexy;

@constant: takes two arguments, the name of the constant and a descriptive text relative to this constant. You could put as many constant tags as there is constants in the enumeration.
 * @enum        fuzzyLogicBoolean_e
 *              Boolean values for fuzzy logic.
 * @constant    FALSE     False value.
 * @constant    TRUE      True value.
 * @constant    PERHAPS   New value, between true and false.
enum   fuzzyLogicBoolean_e {
    FALSE = 0,

You could use this tag when you do a definition of type. It takes just one of the following sub-tags type at the same time.
@field: used when it is a type definition for a structure or an union.

@constant: used when it is for an enumeration type.

@param: used when it is function pointer type.

 * @typedef     cakeRecipe_t
 *              Recipe for most of cakes.
 * @field       eggs     Number of eggs in the cake.
 * @field       milk     Quantity of milk (in litre).
 * @field       choco    Set to TRUE if chocolate is needed.
typedef struct   cakeRecipe_s {
    int          eggs,
    int          milk,
    bool         choco
}                cakeRecipe_t;

 * @typedef     day_t
 *              All week's days.
 * @constant    SUNDAY     First day of week.
 * @constant    MONDAY     Second day of week.
 * @constant    TUESDAY    Third day of week.
 * @constant    WEDNESDAY  Fourth day of week.
 * @constant    THURSDAY   Fifth day of week.
 * @constant    FRIDAY     Sixth day of week.
 * @constant    SATURDAY   seventh day of week.
typedef enum     day_e {
    SUNDAY = 0,
}                day_t;

 * @typedef     crashtestHandler
 *              Function pointer to a crash test action.
 * @param       car          The car on which the test is done.
 * @param       passengers   Number of passengers.
 * @param       speed        Speed of the car.
typedef void (*crastestHandler)(car_t *car, int passengers,
                                int speed);

@define / @defined
This tag takes one argument: the name of the constant. You should explain it utility in the abstract tag. Even if Header Browser do the difference between "constant-like" and "function-like" macros, you don't have anything to do; the difference is set with the source code of the macro.
/*! @define HOMER_SON   Name of the Homer's son */
#define HOMER_SON              "Bart"

/*! @define IS_HOMER_SON  True if it is Bart */
#define IS_HOMER_SON(name)     (!strcmp(name, HOMER_SON))

Previous Page : HeaderBrowser comments
Next Page : C++ specific tags

Copyright © 2000-2001  |  Licence informations