HeaderBrowser

Documentation : Commentaires HeaderBrowser



Forme générale des commentaires
Pour indiquer à Header Browser les informations qu'il doit utiliser, vous devez écrire des commentaires ayant une forme particulère :
/*!
 * @type              Nom
 * @abstract          Documentation résumée pour ce tag.
 * @discussion        Documentation complète pour ce tag.
 * @tag additionnel   Valeur
*/
Comme vous pouvez le voir, les commentaires Header Browser commencent par "/*!", avec un point d'exclamation. Pour garder une certaine compatibilité avec JavaDoc, vous pouvez aussi utiliser "/**".
Il y a certains tags, commençant avec une arobace. Ces tags indiquent à Header Browser une information sur un élément d'API. Dans un commentaire Header Browser, le premier tag exprime le type général de l'API (comme une fonction, un objet, un typedef, ...).

Il y a trois tags que vous pouvez utiliser dans la plupart des tags Header Browser :

@abstract: utilisé pour mettre un résumé de la déclaration d'API. Vous pouvez aussi utiliser le tag @short à la place de abstract, cela revient au même (mais vous ne pouvez pas utiliser les deux en même temps).

@discussion: pour entrer une documentation complète. Si un texte sans tag est trouvé après la déclaration du type et du nom de l'API, il est pris comme étant une discussion.

@see: utilisé pour établir une référence vers une autre documentation. Le tag @ref a exactement le même effet. Vous pouvez mettre autant de tag see que vous voulez, et ils doivent être de la forme suivante.

@see symbol
Réfère à un symbol (fonction, structure, objet, ...) présent dans le même fichier d'en-ête, et du même type (si le tag see est utilisé dans une déclaration function, il ajoute une référence vers une fonction ; utilisé dans un tag header, il réfère un autre fichier d'en-tête, etc.).
@see fichier#
Pointe vers un autre fichier d'en-tête.
@see fichier#symbol
Pointe vers un symbol du même type dans un autre fichier d'en-tête.
@see objet::
Pointe vers un objet présent dans le même fichier.
@see objet::membre
Pointe vers un membre (méthode ou variable) d'un objet présent dans le même fichier.
@see fichier#objet::
Pointe vers un objet dans un autre fichier.
@see fichier#objet::membre
Pointe vers le membre d'un objet présent dans un autre fichier.
Donc vous pouvez créer des déclarations simples :
/*! @var toto_g    Variable globale */
Ou créer des commentaires sur plusieurs lignes, avec ou sans étoile au début de chaque ligne :
/*!
 * @function    pipo
 *              Ici la discussion, ecrite sur 2 ligne,
 *              sans le tag "discussion".
 * @abstract    Le resume.
 @param         Pas d'etoile au debut de cette ligne.
                C'est OK.
@param          Une autre ligne qui fonctionne.
*/

Tags pour tous les fichiers d'en-tête
Il y a un seul tag Header Browser qui est utilisé pour l'ensemble des fichiers d'en-tête. C'est le tag @header (ou @package, c'est la même chose mais vous ne pouvez pas avoir les deux dans le même fichier); Il doit être présent au plus une fois dans un fichier. Ce tag prend un seul argument, qui est le nom du fichier d'en-tête (ou le nom de la fonctionnalité générale) :
/*!
 * @header      toto.h
 * @abstract    Toutes les fonctions toto.
 * @discussion  Ce fichier contient toutes les declarations
 *              pour manipuler des totos.
*/
Vous pouvez écrire de longs textes de discussion, avec des exemples de code. Dans une déclaration @header, vous pouvez utiliser d'autres tags pour ajouter des informations. Ces tags sont : @version, @author, @see, et @link. A part le tag version, tous ces tags peuvent être utilisés plusieurs fois dans le même tag header.
@version: prend en argument un texte contenant le numero de version du fichier et la date de création/modification.

@author: prend en argument le nom et l'adresse eMail de l'auteur du fichier / de la documentation. Vous devez mettre d'abord le nom, puis l'adresse eMail, entre les caractères '<' et '>'.

@link: est à utiliser pour mettre des liens hypertexte (pour la sortie HTML uniquement). Comme pour le tag author, vous devez d'abord mettre le nom du lien, puis l'adresse entre les caractères '<' et '>'.

voyez cet exemple :
/*!
 * @header      toto.h
 * @abstract    Toutes les fonctions toto.
 * @discussion  Ce fichier contient toutes les declarations
 *              pour manipuler des totos.
 * @version     1.0.1 Dec 09 2001
 * @author      yoda <yoda@star.wars>
 * @see         toto2.h#
 * @link        Site Web StarWars <http://www.starwars.com>
 * @ref         xwing::voler
 * @link        Serveur FTP de Yoda <ftp://ftp.yoda.wars>
 * @author      Bart <bart@simpson.com>
*/

Page precedente : Introduction
Page suivante : Tags C/C++


Copyright © 2000-2001  |  Informations sur la licence