Début:

Comment documenter le code source C++ pour Autodoc

Dernière mise à jour : January 14 2005

Contact: Nikolai Pretzell

Traduction française : Eric Bachard Octobre 2005

Contenu

Règles de Base
Cequi peut être documenté
Mise en page
Etiquettes
Etiquettes Communes
Etiquettes de Classes
Etiquettes de Fonctions
Etiquettes de Variables
Etiquettes Globales
Une documentation typique

Objectif

Ceci décrit comment documenter le code C++ de telle façon qu'il soit automatiquement parsé par l'outil de documentation automatique Autodoc (inclus dans les sources d'OpenOffice.org)

Règles de base

Il y a deux possibilités pour documenter du code dans un fichier C++ :
La documentation multi-lignes commence avec /** et se termine avec */ et celà

ressemble à :

/** du texte

.................

.................

*/

Une ligne simple appelée aussi documentation “inline” débute avec /// et se termine avec la ligne, ce qui donne :

/// Du texte .......

Nous appelons “paragraphe documenté” les deux exemples de blocs que nous venons de décrire.

La langue utilisée pour la documentation du code est l'anglais.

Seuls les fichiers d'en-tête sont parsés par Autodoc.

Pour une utilisation plus typique, le style de documentation du code est compatible avec Javadoc. Simplement, vous ne pourrez pas utiliser le slash gauche tel qu'il est utilisé avec Java :

/** Texte

* ...

*/

ne va pas fonctionner.

Attention: Le premier "/**"-commentaire dans chaque fichier est ignoré.

C'est parce qu'Autodoc est usuellement utilisé pour parser des fichiers avec licences- , CVS- or autres en-tête spécifiques qui commencent aussi avec la séquence "/**".
Pour les fichiers ne contenant pas ce type d'en-tête, vous devrez insérer un commentaire vide au début de ceux-ci.

Ce qui peut être documenté

Les entités de code C++ documentables sont :

les classes (structures et unions incluses)

les énumérations

les fonctions / méthodes

les variables (les constantes sont incluses)

les valeurs d'énumérations

#define-s

les macros #define-d

Toute documentation précède le code. S'il y a plus d'un paragraphe de documentation qui se suivent, c'est le dernier qui l'emporte.
Veuillez noter que le premier "/**"-commentaire dans chaque fichier est interprété comme un

en-tête spécial de fichier et n'est pas reconnu par Autodoc.

Mise en page

S'il n'y a pas de @-tag au début d'un paragraphe de documentation, la première partie est interprétée comme @short , de même que s'il n'y a pas plus de deux lignes, suivies par une ligne vide.
Après cette ligne vide, ou s'il y a plus de deux lignes, un texte sans @-étiquette sera interprété comme @descr

La forme suivante devra être utilisée :

Les caractères '*'s ou '#'s ne doivent pas être utilisés dans les lignes de documentation!

Toutes les Etiquettes @-étiquettes doivent être le premier caractères de leur ligne, excepté le /** du début d'un paragraphe de documentation.

La mise en forme suivante est recommandée :

Utiliser la documentation multi ligne (/**...*/).

Commencer la documentation sur la même ligne que /** .

Les signes de début et fin ( /** and */ ) d'une ligne multiple de documentation commencent à la même colonne que l'entité de code documentée.

Chaque ligne de documentation commence 4 colonnes en retrait à droite de chaque étiquette et de chaque caractère de début et fin de documentation (“/** and */”).

Les marques HTML peuvent être utilisées (ou non).
Le défaut est sans HTML. (Cela permet d'écrire la documentation plus simplement et surtout plus rapidement.) Dans ce cas, toutes les fins de lignes et les indentations seront préservées dans la documentation générée. Toutes les choses comme “<BR>” apparaîtront encore sans modification, dans la documentation générée.
Si le HTML doit être utilisé, (pour la publication de bibliothèques, une mise en forme plus sophistiquée peut être souhaitée), ceci peut être fait avec les marques @HTML et @NOHTML . Ces Etiquettes permettent de reconnaître l'état on ou off de la partie HTML, jusqu'à la prochaine étiquette.
Il n'est pas nécessaire d'utiliser le HTML pour créer les liens, dans la plupart des cas.. Voir à

Liens automatiques.

Etiquettes

Légende

A '|' à l'intérieur d'une étiquette

signifie que l'étiquette peut être résumée à cette position

Les mots sur la même ligne que l'étiquette @-étiquette

sont des paramètres de cette étiquette

<ABC>

un paramètre

"par"

Un texte placé entre "" sera utilisé tel quel.

[...]

Les paramètres placés à l'intérieur de [] sont optionnels.

NOTEXT

Il ne peut pas y avoir de texte ajouté à cette étiquette.

Toutes les étiquettes avec paramètres ne peuvent plus avoir de texte dans la même ligne, après les paramètres. Les paramètres non entourés de crochets de type [] sont requis et doivent être spécifiés.

étiquette paramètre-requis [paramètre-optionnel]

Etiquettes communes

@ATT|ENTION

À utiliser si l'utilisation intuitive d'une fonction peut donner lieu à des erreurs. Ou si celle-ci doit être utilisée seulement dans des circonstances spécifiques.

@author <Un.Name>

Auteur du code. À modifier par la (dernière) personne, qui a procédé à des changements, et donc est responsable du présent code. Si cette personne, qui a effectué les dernières modifications, n'est pas responsable du code (par exemple, parce que l'auteur est en congés) , la étiquette @change doit être utilisée. Cette étiquette peut être utilisée hierarchiquement : Si une étiquette auteur se trouve dans la documentation de classe, seuls certains membres en nécessitent une. Si une étiquette auteur se trouve aussi dans le membre, il appartient seulement à celui-ci. Même chose pour les énumérations, ainsi que pour leurs valeurs.
NOTEXT.

@change <jj.mm.aaaa> "par" <QuiAFaitLaModification>

Désigne une étiquette de modification @change pour chaque modification, à commencer par la dernière.

@deprecated

Marque une entité de code qui n'est conservée que pour des raisons de compatibilité.
NOTEXT

@descr

Le principal texte décrivant le contenu du document.
Cette étiquette peut être omise avant le texte (voir Une documentation Typique ).

@docdate <jj.mm.aaaa>

Date de création de la documentation. La dernière date, lorsque la documentation a été modifiée.
NOTEXT.

@empty

étiquette spéciale pour la documentation testée. Cela signifie, ici, que de manière intentionnelle, aucune documentation n'est présente.
NOTEXT.

@internal

Typiquement utilisé pour fonctions cachées ou non exportées. La documentation pour ce code peut être filtrée indépendamment de la documentation crée.
NOTEXT.

@key <MotClé>

Cette étiquette donne la possibilité de rechercher dans le document créé, ou de le filtrer, avec une clé donnée.
Une étiquette pour chaque clé.
À utiliser avec précaution. Utiliser trop de clés diminue la clarté. Il est peut-être possible que des mots clé, dans un projet, puissent être définis par l'équipe.

NOTEXT.

@see|also >>CeQuiEstAVoir<<

Ajoute un point de documentation sur une entité de code donnée.
NOTEXT.

@short

Un court texte (juste une ligne typiquement) décrivant l'entité documentée. En l'occurence, cela peut être utilisé en tant qu'indice de sous forme de courte description.
L'étiquette peut être omise avant ce texte (voir Une Documentation typique ).

@todo

Taches qui sont à terminer avec une entité de code.

Etiquettes de Classes

@base >>ClasseDeBase<<

Commentaire d'une classe de base.
Utiliser uniquement s'il y a des commentaires. Une liste simple des classes est automatiquement créée par Autodoc.

@collab|orator >>LeCollaborateur<<

Ceci est utilisé dans le sens des cartes CRC.
Une étiquette pour chaque collaborateur.

@derive

Si la classe est utilisée pour être héritée, ici peut être décrit comment cela est réalisé : quelles méthodes doivent être réécrites, lesquelles ne doivent pas, etc.

@instance <Nomd'Objet>

Décrit une instance spécifique de cette classe..
Une étiquette pour chaque instance.

@interface

Cette étiquette dit que cette classe doit être utilisée seulement en tant que classe et implémentation dans les classes dérivées.
NOTEXT.

@invariant

Peut être utilisé pour les invariants formels de cette classe. Recommandé pour l'utilisation publique de classes/interfaces.

@resp|onsibility

Doit être utilisé dans le sens des cartes CRC .
Une étiquette pour chaque responsabilité.

@tpl|param <TemplateNomParamètre>

Réservé aux modèles. Décrit un paramètre de modèle : sens, pré-requis, restrictions.
Une seul étiquette pour chaque paramètre de modèle.

Etiquettes de Fonctions

@exception >>Typed'Exception<<

Décrit une exception.
Une étiquette pour chaque exception.
Utiliser ceci seulement s'il y a des commentaires. La liste simple des exceptions est automatiquement créée par Autodoc.

@invariant

Peut être utilisé pour des invariants formels de cette fonction.

@onerror

Considéré comme condition d'erreurs. Peut être utilisé s'il n'y a pas de spécification d'exception.

@param <NomParamètre> [ "["<ValeursPossibles> "]" ]

Décrit un paramètre de fonction.
Le domaine de valeurs possibles est optionnel, mais les '[' et ']' doivent littéralement être présents, si un domaine de valeurs est précisé. (Cette notation ne signifie pas “paramètres optionnels” ici [NDT : c'est la notation habituellement consacrée]" ).
Une étiquette pour chaque paramètre.
N'utiliser ceci que s'il y a des commentaires à ajouter, car une liste des paramètres est automatiquement créée.

@postcond

Peut être utilisée pour des post-conditions formelles de cette fonction. Recommandé pour l'utilisation publique de bibliothèques de fonctions.

@precond

Peut être utilisé pour des pré-conditions formelles de cette fonction. Recommandé pour l'utilisation publique de bibliothèques de fonctions.

@return

Décrit la valeur de retour de cette fonction.

@tpl|param <TemplateNomParamètre>

Reservé aux modèles. Décrit un paramètre de modèle : sens, pré-requis, restrictions.
Un seul tag pour chaque paramètre de modèle.

Etiquettes de Variables

@dyn

Ceci définit une variable pointeur gérant un objet de la pile. Utilisé dans un but bien défini. il est toujours clair, en tant que pointeur, qu'il doit être effacé sauf s'il n'est qu'un référencement. Ce tag ne doit pas être compté pour le comptage des objets de référence en mémoire. S'il existe, il signifie toujours : utiliser delete pour cette variable, ou le transmettre à quelque chose qui l'effacera de la mémoire.

@life|cycle

Décrit quand une variable est créée / détruite.

@multi|plicity <Range>

Le domaine de valeurs possibles peut être quelque chose comme “1+”, “0+”, “2..5”, “Chaînes jusqu'à 255 caractères”.

Etiquettes globales

@HTML

Pour le reste du fichier source (sinon jusqu'au prochain @NOHTML ), HTML-Etiquettes dans la documentation sera reconnu comme tel.

@NOHTML

Pour le reste du fichier source (ou jusqu'au prochain @HTML ), les HTML-Etiquettes dans la documentation seront ignorées et considérées comme du texte normal, ie. Non traduit.

Une documentation de code typique

/** Commentaire court : C'est pour .... .

Après une ligne vide, ici commence la description de la partie code.

Ici peut se trouver un texte plus long, par exemple, des considérations

philosophiques et des descriptions de solutions spécifiques.

Après ce texte, seuls les @-Etiquettes sont autorisés.

Chacun des textes suivants est précédé de son @-tag qui le caractérise

@param entier1 [0 .. 255]

Décrit le paramètre entier1.

@param str2

Décrit le paramètre entier2.

@return vrai, si tout est ok. Sinon faux.

*/

bool funct_00( int entier1, const char * str2 );

Sophie Gautier Ménard Terret

2005-10-24T16:08:04