Header Browser's Documentation : HeaderBrowser Comments

General form of comments
To show HeaderBrowser documentation informations, you have to write some comments in a particuliar form :
 * @type              Name
 * @abstract          Summarized documentation for this tag.
 * @discussion        Full documentation for this tag.
 * @additional tag    Value
As you see, HeaderBrowser comments begins by "/*!", with an exclamation mark. For compatibility with JavaDoc, you also could use "/**".
There is some "tags", begining with an arobase. These tags indicates an HeaderBrowser API information. In a HeaderBrowser comment, the first tag is for the general API type (like function, class, typedef, ...).

There is three tags that you could use in most of general HeaderBrowser tags :

@abstract: used to put a brief guide of the API declaration. You also could use @short tag instead of abstract, it's the same (but you couldn't use the both at the same time).

@discussion: it is for complete documentation. If an untagged text is finded after the API type and name declarations, it will be taken as a discussion.

@see: used to refere to other related documentation. The @ref tag have exactly the same effect. You could put as see tags as you want, and they must be like the following forms.

@see symbol
Refere to a symbol (function, struct, object, ...) in the same header file, and with the same type (i.e. if the see is used in a function declaration, it refere a function ; if it used in an header tag, it refere another header file, etc.).
@see headerfile#
Refere to another header file.
@see headerfile#symbol
Refere to a symbol of the same type in other header file.
@see object::
Refere to an object in the same header file.
@see object::member
Refere to a member (method or variable) of an object in the same header file.
@see headerfile#object::
Refere to an object in another header file.
@see headerfile#object::member
Refere to a member of an object in another header file.
So, you can create simple declarations:
/*! @var foo_global    Global variable */
Or create multi-lines comments, with or without asterisks at the beginning of each lines:
 * @function    foo_function
 *              Here is the discussion, written on 2 lines,
 *              without the discussion tag.
 * @abstract    The summary.
 @param         No asterisk on this line; it's still good.
@param          Another fine-working example.

Tags for all headers file
There is only one HeaderBrowser tag used for the whole header file. It is the @header tag (or the @package, it's the same but you couldn't have the both in the same file); it must be at most one time in the file. This tag takes only one field, which is the name of the header file (or the general functionality name) :
 * @header      foo.h
 * @abstract    All foo functions.
 * @discussion  This file contains all declarations for
 *              foo manipulation.
You could write long discussion text, with example code. Inside an @header declaration, you could use other tags, to add more informations. These tags are : @version, @author, @see, and @link. Living aside the version tag, all of these tags could be used many times in the same header tag.
@version: takes as argument a text which contains the version number of the file, and the date of creation/modification.

@author: takes as argument the name and the eMail adress of the header/documentation author. You must type the name first, and after the eMail adresse, between '<' and '>' characters.

@link: it is here to put hypertext links (in HTML output only). Like for the author tag, you must type the name of the link, and after the address between '<' and '>' characters.

See this example :
 * @header      foo.h
 * @abstract    All foo functions.
 * @discussion  This file contains all declarations for
 *              foo manipulation.
 * @version     1.0.1 Dec 09 2001
 * @author      yoda <yoda@star.wars>
 * @see         foo2.h#
 * @link        Starwars Web site <http://www.starwars.com>
 * @ref         xwing::fly
 * @link        Yoda's FTP <ftp://ftp.yoda.wars>
 * @author      Bart <bart@simpson.com>

Previous Page : Introduction
Next Page : C/C++ tags

Copyright © 2000-2001  |  Licence informations