Scope

Ce document décrit comment écrire de la documentation avec son code source de manière à permettre de la traiter automatiquement par notre outil interne de documentation, Autodoc.
En outre, ce document fait mention des conditions à remplir afin de faire de la documentation, conditions qui ont été convenues pour le Kit de Développement de l'Office (ODK). D'autres projets pourraient éventuellement s'en inspirer.

Règles de Base

• Il y a deux manières d'inclure de la documentation dans un fichier C++ :
  De la documentation sur plusieurs lignes commencent par /** et se termine en */ et ressemble donc à ceci:

  /** un peu de texte
      .................
      .................
  */

  De la documentation sur une seule ligne ou “intégrée en ligne” commence par /// et se termine par la fin de la ligne, et prend donc cette forme :

  ///  un peu de texte .......
  

  A “paragraphe de documentation” on peut utiliser l'une quelconque des méthodes décritrent ci-dessus.

• Le langage de la documentation est l'anglais.
• Pour l'instant, seuls les fichiers d'en-tête sont traités par Autodoc.
• La plupart du temps, le style de documentation est compatible à celui de Javadoc : Ce qui fonctionne avec Javadoc, devrait fonctionner avec Autodoc. Il existe pourtant quelques plus.

Qu'est-ce qu'on peut documenter ?

Les entités de code pouvant faire l'objet d'une documentation en C++ sont:

• les classes (y compris les structs et unions)
• les enums
• les fonctions / méthodes
• les variables (y compris les constantes)
• les valeurs enum
• les #define-s
• les macro #define-d.

Toute la documentation appartient à l'entité de code qui la suit et pouvant faire l'objet d'une documentation. Si plusieurs paragraphes de documentation se suivent, le dernier l'emporte.

[DEBUT  - N'EST VALABLE QU'A PARTIR DE : Autodoc Version 2.3, attendue en juillet 2002 ]

Une exception est constituée par de la documentation intégrée qui suit une déclaration quelconque. De la documentation intégrée en ligne est possible pour :

• les classes de base
• les paramètres de fonction
• les valeurs enum.

On ne peut utiliser qu'une virgule ',' entre l'entité documentée et la documentation intégrée en ligne. Aucun autre texte ni commentaire n'est permis. La documentation intégrée en ligne doit commencer par /// . La documentation intégrée en ligne ne peut remplacer de la documentation antérieure, mais, doit être, par exemple dans le cas de la documentation intégrée en ligne d'un paramètre, ajoutée à la documentation précédente relative à la fonction dans son ensemble.

Les éléments suivants peuvent également faire l'objet d'une documentation:

• les espaces de noms
• les fichiers de code source
• les termes d'un glossaire

Pour les détails, voir les balises @namespace , @file et @glossary ci-dessous.

[FIN - N'EST VALABLE QU'A PARTIR DE : Autodoc Version 2.3 ]

Mise en page

S'il n'existe aucune balise @-tag au début d'un paragraphe de documentation, la première partie est interprétée comme s'il s'agissait de @short , si elle ne dépasse pas les deux lignes et est suivie d'une ligne vide.
A partir de cette ligne vide, ou s'il y a plus de deux lignes, du texte sans la balise @-tag est interprété comme étant @descr .

La mise en page suivante est obligatoire :

• Des entrées commençant par '*'s ou '#'s dans chaque ligne de documentation ne doivent pas être utilsées!
• Toutes les balises @-tags doivent être les premiers éléments ne constituant pas d'espaces blancs dans leur ligne, sauf au /** début d'un paragraphe de documentation.

La mise en page suivante est recommandée:

• Utilisation de la documentation à plusieurs lignes (/**...*/).
• Commencez la documentation sur la même ligne que les /** .
• Les signes de début et de fin ( /** et */ ) d'un début de documentation à lignes multiples sont placés dans la même colonne que l'entité de code documenté.
• Chaque ligne et chaque balise font débuter 4 colonnes à la droite des signes de début et de fin (“/** et */”).

Les balises HTML peuvent être utilisées en option.
Par défaut, on n'utilise pas le HTML. ( La raison en est que cela est plus facile et plus rapide. Si la documentation est plus facile à faire, il y a plus de chances qu'elle soit faite. ) Dans ce cas, tous les sauts de ligne et toutes les indentations seront conservés dans la documentation générée par la suite. Tout le reste, par exemple “<BR>” apparaîtra sans modification, dans la documentation générée.
Si on doit utiliser du HTML (par exemple pour les besoins de bibliothèques publiques, une mise en page plus sophistiquée pourrait être souhaitée), alors dans ce cas, on peut utiliser les balises @HTML et @NOHTML . Ces balises activent ou désactivent la reconnaissance du code HTML pour le reste du fichier, ou jusqu'à ce qu'on rencontre la balise suivante.
Il n'est pas nécessaire d'utiliser du HTML pour générer les liens, dans la plupart des cas. Voir également Liens Automatiques.

Balises

Un '|' se trouvant dans une balise

signifie que la balise peut être raccourcie à cette position.

Des mots se trouvant dans la même ligne que la balise @-tag

sont des paramètres de celle-ci.

<ABC>

un paramètre

>>Xyz<<

Xyz sera interpreté comme un lien automatique

"par"

paramètres se trouvant entre "" est à prendre à la lettre.

[...]

Des paramètres se trouvant entre [] sont optionnels.

NOTEXT

Il ne peut y avoir de texte supplémentaire à cette balise.

Les balises comportant des paramètres ne peuvent avoir du texte supplémentaire dans la même ligne suivant les paramètres. Les paramètres qui ne sont pas enfermés par des parenthèses [] sont obligatoires et doivent être spécifiés.

balise  paramètre requis [paramètre optionnel]

Balises pour toutes les entités de code

@ATT|ENTION

doit être utilisé, si l'utilisation intuitive d'une fonction peut être fausse. Ou si elle ne doit être utilisée dans des circonstances très spécifiques.

@author <Un.Nom>

Créateur du code. Ceci est modifié pour indiquer la dernière personne ayant effectué des changements dans le code, et qui est responsable du code (peut être, parce que l'auteur était en vacances), la balise @change doit être utilisée. Cette balise peut être utilisée de manière hiérarchique: S'il existe une balise auteur dans la documentation de classe, il n'est pas nécessaire que chaque membre ait la sienne. S'il existe une balise auteur dans un membre également, elle appartient uniquement à ce membre. La même chose s'applique pour les enums et leurs valeurs.
NOTEXT.

@change <dd.mm.yyyy> "par" <Quiafaitlechangement>

Il doit y avoir une nouvelle balise @change pour chaque changement, la plus récente en première.

@deprecated

Identifie une entité de code comme n'existant que pour la rétrocompatibilité.
NOTEXT

@descr

Le texte principal décrivant l'entité documentée.
La balise peut être omise avant ce texte (voir Commentaire Type sur la Documentation ).

@docdate <dd.mm.yyyy>

Date de la documentation. La dernière date à laquelle la documentation a été modifiée.
NOTEXT.

@empty

Balise spéciale pour la documentation qui a été testée. Cela veut dire, ici, qu'aucune documentation n'est voulue.

@@@@Je ne comprends pas ce que ceci est supposé faire...

NOTEXT.

@internal

Typiquement utilisée not pour des fonctions exportées ou autrement cachées. La documentation pour cette entité de code peut être éliminée de la documentation créée.
NOTEXT.

@key <MotClé>

Cette balise donne la possibilité de rechercher dans la documentation créée ou de la filtrer, avec la clé donnée.
Une balise pour chaque clé.
A utiliser avec précaution. Un excès de clés nuit à la clarté générale. Il serait peut être judicieux que les mots clés dans un projet soient définis par l'équipe de développement.
NOTEXT.

@see|also >>AVoir<<

Cette balise pointe vers une entité de code liée.
NOTEXT.

@short

Un petit texte (typiquement une seule ligne) décrivant l'entité documenté. Par exemple, ce texte peut être utilisé dans des indices en tant que courte description.
La balise peut être omise avant ce texte (voir Commentaire Type sur la Documentation ).

@todo

Tâches qui ne sont pas encore accomplies par rapport à une entité de code.

Balises spéciales pour des Classes

@base >>ClassedeBase<<

Commentaire d'une classe de base.
A n'utiliser que s'il y a des commentaires. Le listage simple de classes de base est fait de manière automatique.

@collab|orator >>LeCollaborateur<<

>Ceci est utilisé dans le sens des Cartes CRC .
Une balise pour chaque collaborateur.

@derive

Si la classe est conçue pour être dérivée, on peut décrire ici comment le faire : Lesquelles des méthodes doivent être réécrites, lesquelles non, etc.

@instance <NomObjet>

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

@interface

Cette balise indique que la classe n'est à utiliser en tant qu'interface et l'implémentation se fait dans des classes dérivées.
NOTEXT.

@invariant

Celle-ci peut être utilisée pour des invariables formels de cette classe. Elle est conseillée pour des classes/interfaces utilisées publiquement.

@resp|onsibility

Celle-ci doit être utilisée dans le sens des Cartes CRC .
Une balise pour chaque responsabilité.

@tpl|param <TplParamName>

Uniquement pour des modèles. Décrit un paramètre de modèle: signification, conditions, restrictions.
Une balise pour chaque paramètre de modèle.

Balises spéciales pour fonctions/méthodes

@exception >>TypeException<<

Décrit une exception.
Une balise pour chaque exception.
A n'utiliser que s'il y a des commentaires. Le listage simple d'exceptions est fait de manière automatique.

@invariant

Peut être utilisée pour des invariables formels de la fonction. 

@onerror

Gestion des exceptions. Peut être utilisée si aucune spécification d'exception n'est faite.

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

Décrit un paramètre de fonction.
La plage est optionnelle, mais les '[' et ']' doivent être là, si une plage est donnée. (Ce ne sont pas des signes de "paramètre optionnel" ici).
Une balise pour chaque paramètre.
A n'utiliser que s'il y a des commentaires. Le listage simple de paramètres se fait de manière automatique.

@postcond

Peut être utilisée pour les post-conditions formelles de cette fonction. Conseillée pour des fonctions de bibliothèques publiques.

@precond

Peut être utilisée pour des préconditions formelles de cette fonction. Conseillée pour des fonctions de bibliothèques publiques.

@return

Décrit les valeurs de retour de la fonction.

@tpl|param <TplParameterName>

Uniquement pour des modèles. Décrit un paramètre de modèle: signification, conditions, restrictions.
Une balise pour chaque paramètre de modèle.

Balises spéciales pour Variables

@dyn

Celle-ci indique un pointeur de variable en tant que propriétaire d'un objet de tas. Si utilisée, il doit toujours être clair si le pointeur doit être supprimé ou s'il n'est présent que pour référence. Cette balise ne doit pas être utilisée pour des objets refcount. Si elle existe, elle signifie toujours: Utiliser Supprimer sur cette variable, ou la faire passer à quelqu'un d'autre, qui la supprimera de manière certaine.

@life|cycle

Décrit le moment de la création et de la destruction d'une variable.

@multi|plicity <Plage>

La plage peut être quelque chose du genre “1+”, “0+”, “2..5”, “ jusqu'à 255 caractères ”.

Balises Globales

@HTML

Valable pour le reste du fichier code source (ou jusqu'à la prochaine balise @NOHTML ), les balises HTML dans la documentation seront reconnues en tant que telles.

@NOHTML

Valable pour le reste du fichier code source (ou jusqu'à la prochaine balise @HTML ), les balises HTML dans la documentation seront ignorées et considérées comme du texte normal, c-à-d. ne seront pas traduites.

[DEBUT -  N'EST VALABLE QU'A PARTIR DE: Autodoc Version 2.3, attendue en juillet 2002 ]
@file

Cette balise doit être la première dans les commentaires de la documentation (/** */), et est destinée à l'ensemble d'un fichier code source . Il est conseillé de mettre ce commentaire de documentation devant tous les autres. La balise @file doit se trouver seule dans une ligne sans aucun autre texte (NOTEXT).
Tout texte suivant est traité comme s'il était au début du paragraphe de documentation . Voir aussi Commentaire Type de Documentation La documentation après @file appartient au fichier, dans lequel elle est écrite.
Nota: Autodoc ne tient pas compte du fichier d'en-tête standard comportant des clauses de licence, droit d'auteur, etc comme un commentaire de documentation, bien que cela puisse commencer par /**********. Ceci est reconnu par la balise CVS “$workfile”. Ainsi, “$workfile” ne doit pas apparaître dans une documentation de code source.

@glos|sary <TermeDécrit>

Cette balise peut être utilisée partout. Elle définit un terme public connu. Le terme est défini par le texte suivant. Chaque entrée de ce terme (sensible à la casse) dans la documentation sera liée à cette définition.
Le terme décrit ne peut qu'être constitué de caractères alphanumériques ( [A-Za-z0-9]+ ) .

@glos|sary <TermeDécrit> <LienHypertexte>

Cette balise peut être utilisée partout. Elle définit un terme public connu . Il n'y a pas de texte qui définit le terme, mais un lien vers la definition. Toutes les entrées de ce terme (sensible à la casse) dans la documentation seront liées à cette définition.
Le terme décrit ne peut qu'être constitué de caractères alphanumériques ( [A-Za-z0-9]+ ) .

@namespace <EspaceNomPleinementQualifié>

Celle-ci fonctionne comme @file, mais la documentation appartient à l'espace de nom donné. Cette balise peut être utilisée partout, même dans des fichiers qui n'utilisent pas le nom d'espace donné

Commentaire Type de Documentation

/** Bref Commentaire: Ceci est pour .... .
    
    Après une ligne vide, voici la description principale de l'entité de code. Ici on peut inclure un texte plus long, des exemples, 
    des considérations philosophiques et des descriptions de solutions spéciales. 
    On ne peut utiliser que des balises  @-tags après ce texte. Chaque texte suivant appartient à la balise qui précède @-tag. 
    
    @param integer1 [0 .. 255]
    Describe parameter integer1.
    
    @param str2 
    Describe the parameter str2.

    @return true, if everything is ok. Else false.
*/
bool   funct_00( int integer1, const char * str2 );


[DEBUT - VALIDE SEULEMENT A PARTIR DE: Autodoc Version 2.3, attendue Juillet 2002 ]

Liens Automatiques

Des noms de type (classes et structs, enums, typedefs), valeurs d'enum et variables dans la même portée de noms (espace de noms ou classe) sont liés. Des noms de fonction dans la même portée de noms sont liés, si le nom de la fonction se termine en "() ".

Toutes les entités qui ne se trouvent pas dans la même portée de noms, sont liées, si elles sont référencées avec leurs noms complets pleinement qualifiés, c'est-à-dire qu'ils commencent par " :: ". Ici encore, les fonctions doivent se terminer en "()".

Bien entendu, la reconnaissance de tels noms est sensible à la casse et aux formes plurielles. Ils doivent être écrits exactement tels qu'ils sont.

OpenOffice.org native tongue concept and francophone project are built for you with pride by Guy Capra (Alomphega).
This fr project is also led and maintained by Sophie Gautier.