content/fr/Laboratory/autodoc_cpp.html - openoffice-org - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
 <html>
 <head>
   <title>Labo</title>
   <meta http-equiv="content-type" content="text/html; charset=UTF-8">
 </head>
 <body>
 <table border="0" cellpadding="4" width="100%">
   <tbody>
     <tr>
       <td align="left" valign="top" width="100%"><!-- Content -->
       <div align="center">
       <h3 style="text-align: left;">Comment écrire de la Documentation
 de Code Source en C++</h3>
       <div align="right"><b> Dernière mise à jour: 29.5.2003</b><br>
       </div>
       <div align="right">
       <p><font size="3"><b>Contact: </b><a
  href="mailto:nikolai@sun.com"> Nikolai Pretzell</a> </font><br>
       </p>
       </div>
       </div>
       <h3>Scope</h3>
       <p>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.<br>
 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.<br>
       <br>
       </p>
       <h3>Règles de Base</h3>
       <ul>
         <li>
           <p>Il y a deux manières d'inclure de la documentation dans un
 fichier C++ :<br>
 De la documentation sur plusieurs lignes commencent par <span style=""><font
  face="Courier New, monospace"> /**</font></span> et se termine en <span
  style=""><font face="Courier New, monospace"> */</font></span> et
 ressemble donc à ceci: </p>
           <pre>/** un peu de texte<br>    .................<br>    .................<br>*/</pre>
           <p> De la documentation sur une seule ligne ou “intégrée en
 ligne” commence par <font face="Courier New, monospace"> /// </font>
 et se termine par la fin de la ligne, et prend donc cette forme : </p>
           <pre>///  un peu de texte .......<br></pre>
           <p>A “paragraphe de documentation” on peut utiliser l'une
 quelconque des méthodes décritrent ci-dessus. </p>
         </li>
         <li> Le langage de la documentation est l'anglais.</li>
         <li>Pour l'instant, seuls les fichiers d'en-tête sont traités
 par Autodoc.</li>
         <li>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.</li>
       </ul>
       <h3>Qu'est-ce qu'on peut documenter ?</h3>
       <p>Les entités de code pouvant faire l'objet d'une documentation
 en C++ sont: </p>
       <ul>
         <li>les classes (y compris les structs et unions)</li>
         <li>les enums</li>
         <li>les fonctions / méthodes</li>
         <li>les variables (y compris les constantes)</li>
         <li>les valeurs enum </li>
         <li>les #define-s </li>
         <li>les macro #define-d. </li>
       </ul>
       <p>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.</p>
       <p><br>
 [DEBUT&nbsp; - N'EST VALABLE QU'A PARTIR DE : Autodoc Version 2.3,
 attendue en juillet 2002 ]<br>
       </p>
       <p> 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 :</p>
       <ul>
         <li>les classes de base</li>
         <li>les paramètres de fonction</li>
         <li>les valeurs enum.</li>
       </ul>
       <p>On ne peut utiliser qu'une virgule '<tt>,</tt>' 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 <tt>///
 . 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.</tt></p>
       <p> Les éléments suivants peuvent également faire l'objet d'une
 documentation:<br>
       </p>
       <ul>
         <li>les espaces de noms</li>
         <li> les fichiers de code source</li>
         <li> les termes d'un glossaire</li>
       </ul>
       <p>Pour les détails, voir les balises <a
  href="../Labo/fran%E7ais/HowToWriteDocumentation-Cpp_fr.html#at_namespace">@namespace</a>
 , <a
  href="../Labo/fran%E7ais/HowToWriteDocumentation-Cpp_fr.html#at_file">@file</a>
 et <a
  href="../Labo/fran%E7ais/HowToWriteDocumentation-Cpp_fr.html#at_glos">@glossary</a>
 ci-dessous.</p>
       <p>[FIN - N'EST VALABLE QU'A PARTIR DE : Autodoc Version 2.3 ]<br>
       <br>
       </p>
       <h3>Mise en page</h3>
       <p>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 <a
  href="../Labo/fran%E7ais/HowToWriteDocumentation-Cpp_fr.html#at_short">@short</a>
 , si elle ne dépasse pas les deux lignes et est suivie d'une ligne vide.<br>
 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 <a
  href="../Labo/fran%E7ais/HowToWriteDocumentation-Cpp_fr.html#at_descr">
 @descr</a> .</p>
       <p>La mise en page suivante est obligatoire :</p>
       <ul>
         <li>Des entrées commençant par '*'s ou '#'s dans chaque ligne
 de documentation ne doivent pas être utilsées! </li>
         <li>Toutes les balises @-tags doivent être les premiers
 éléments ne
 constituant pas d'espaces blancs dans leur ligne, sauf au <tt>/**
 début </tt>d'un paragraphe de documentation.</li>
       </ul>
       <p>La mise en page suivante est recommandée:</p>
       <ul>
         <li>Utilisation de la documentation à plusieurs lignes
 (/**...*/).</li>
         <li> Commencez la documentation sur la même ligne que
 les <tt> /**</tt> .</li>
         <li> Les signes de début et de fin ( <tt>/**</tt> et <tt>
 */</tt> ) d'un début de documentation à lignes multiples sont placés
 dans la même colonne
 que l'entité de code documenté.</li>
         <li> Chaque ligne et chaque balise font débuter 4 colonnes à la
 droite des signes de début et de fin (“/** et */”). </li>
       </ul>
       <p>Les balises HTML peuvent être utilisées en option.<br>
 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 “&lt;BR&gt;”
 apparaîtra
 sans modification, dans la documentation générée.<br>
 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 <a
  href="../Labo/fran%E7ais/HowToWriteDocumentation-Cpp_fr.html#at_html">
 @HTML</a> et <a
  href="../Labo/fran%E7ais/HowToWriteDocumentation-Cpp_fr.html#at_nohtml">@NOHTML</a>
 . 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.<br>
 Il n'est pas nécessaire d'utiliser du HTML pour générer les liens, dans
 la plupart des cas. Voir également <a
  href="../Labo/fran%E7ais/HowToWriteDocumentation-Cpp_fr.html#link">
 Liens Automatiques.</a> <br>
       </p>
       <h3>Balises</h3>
 Légende:<br>
       <blockquote>
         <dl>
           <dt>Un '|' se trouvant dans une balise </dt>
           <dd>signifie que la balise peut être raccourcie à cette
 position.<br>
           </dd>
           <dt>Des mots se trouvant dans la même ligne que la balise
 @-tag</dt>
           <dd> sont des paramètres de celle-ci.</dd>
           <dt> &lt;ABC&gt;</dt>
           <dd>un paramètre</dd>
           <dt>&gt;&gt;Xyz&lt;&lt;</dt>
           <dd>Xyz sera interpreté comme un <a
  href="../Labo/fran%E7ais/HowToWriteDocumentation-Cpp_fr.html#link">lien
 automatique</a> <br>
           </dd>
           <dt> "par" </dt>
           <dd> paramètres se trouvant entre "" est à prendre à la
 lettre. </dd>
           <dt>[...] </dt>
           <dd>Des paramètres se trouvant entre [] sont optionnels.</dd>
           <dt>NOTEXT</dt>
           <dd>Il ne peut y avoir de texte supplémentaire à cette
 balise. </dd>
         </dl>
       </blockquote>
       <p>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. </p>
       <pre>balise  paramètre requis [paramètre optionnel]<br></pre>
       <h5>Balises pour toutes les entités de code</h5>
       <dl>
         <dt>@ATT|ENTION</dt>
         <dd>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.</dd>
         <dt>@author &lt;Un.Nom&gt;</dt>
         <dd>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.<br>
 NOTEXT.</dd>
         <dt>@change &lt;dd.mm.yyyy&gt; "par"
 &lt;Quiafaitlechangement&gt;</dt>
         <dd>Il doit y avoir une nouvelle balise @change pour chaque
 changement, la plus récente en première.</dd>
         <dt>@deprecated</dt>
         <dd>Identifie une entité de code comme n'existant que pour la
 rétrocompatibilité.<br>
 NOTEXT</dd>
         <dt><a name="at_descr"></a> @descr</dt>
         <dd>Le texte principal décrivant l'entité documentée.<br>
 La balise peut être omise avant ce texte (voir <a
  href="../Labo/fran%E7ais/HowToWriteDocumentation-Cpp_fr.html#typic">
 Commentaire Type sur la Documentation</a> ).</dd>
         <dt>@docdate &lt;dd.mm.yyyy&gt;</dt>
         <dd>Date de la documentation. La dernière date à laquelle la
 documentation a été modifiée.<br>
 NOTEXT.</dd>
         <dt>@empty</dt>
         <dd>Balise spéciale pour la documentation qui a été testée.
 Cela veut dire, ici, qu'aucune documentation n'est voulue.<br>
           <p><b>@@@@Je ne comprends pas ce que ceci est supposé faire...</b></p>
 NOTEXT.<br>
         </dd>
         <dt>@internal</dt>
         <dd>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.<br>
 NOTEXT.</dd>
         <dt>@key &lt;MotClé&gt;</dt>
         <dd>Cette balise
 donne la possibilité de rechercher dans la documentation créée ou de la
 filtrer, avec la clé donnée.<br>
 Une balise pour chaque clé. <br>
 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.<br>
 NOTEXT.</dd>
         <dt>@see|also &gt;&gt;AVoir&lt;&lt;</dt>
         <dd>Cette balise pointe vers une entité de code liée. <br>
 NOTEXT.</dd>
         <dt><a name="at_short"></a> @short</dt>
         <dd>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.<br>
 La balise peut être omise avant ce texte (voir <a
  href="../Labo/fran%E7ais/HowToWriteDocumentation-Cpp_fr.html#typic">
 Commentaire Type sur la Documentation</a> ).</dd>
         <dt> @todo</dt>
         <dd> Tâches qui ne sont pas encore accomplies par rapport à une
 entité de code.</dd>
       </dl>
       <h5> Balises spéciales pour des Classes</h5>
       <dl>
         <dt> @base &gt;&gt;ClassedeBase&lt;&lt;</dt>
         <dd> Commentaire d'une classe de base. <br>
 A n'utiliser que s'il y a des commentaires. Le listage simple
 de classes de base est fait de manière automatique.</dd>
         <dt> @collab|orator &gt;&gt;LeCollaborateur&lt;&lt;</dt>
         <dd> &gt;Ceci est utilisé dans le sens des Cartes CRC <a
  href="http://c2.com/cgi/wiki?CrcCards"> </a> .<br>
 Une balise pour chaque collaborateur.</dd>
         <dt> @derive</dt>
         <dd>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.</dd>
         <dt> @instance &lt;NomObjet&gt;</dt>
         <dd> Décrit une instance spécifique de cette classe.<br>
 Une balise pour chaque instance.</dd>
         <dt> @interface</dt>
         <dd> 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.<br>
 NOTEXT.</dd>
         <dt> @invariant</dt>
         <dd> Celle-ci peut être utilisée pour des invariables formels
 de cette classe. Elle est conseillée pour des classes/interfaces
 utilisées publiquement.</dd>
         <dt> @resp|onsibility </dt>
         <dd> Celle-ci doit être utilisée dans le sens des Cartes CRC <a
  href="http://c2.com/cgi/wiki?CrcCards"> </a> .<br>
 Une balise pour chaque responsabilité.</dd>
         <dt> @tpl|param &lt;TplParamName&gt;</dt>
         <dd> Uniquement pour des modèles. Décrit un paramètre de
 modèle:
 signification, conditions, restrictions.<br>
 Une balise pour chaque paramètre de modèle.<br>
         </dd>
       </dl>
       <h5> Balises spéciales pour fonctions/méthodes</h5>
       <dl>
         <dt> @exception &gt;&gt;TypeException&lt;&lt;</dt>
         <dd> Décrit une exception.<br>
 Une balise pour chaque exception.<br>
 A n'utiliser que s'il y a des commentaires. Le listage
 simple d'exceptions est fait de manière automatique.</dd>
         <dt> @invariant</dt>
         <dd> Peut être utilisée pour des invariables formels de la
 fonction.&nbsp;</dd>
         <dt> @onerror</dt>
         <dd> Gestion des exceptions. Peut être utilisée si aucune
 spécification d'exception n'est faite.</dd>
         <dt> @param &lt;NomParamètre&gt; [ "["&lt;PlageValide&gt; "]" ]</dt>
         <dd> Décrit un paramètre de fonction. <br>
 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).<br>
 Une balise pour chaque paramètre.<br>
 A n'utiliser que s'il y a des commentaires. Le listage simple
 de paramètres se fait de manière automatique.</dd>
         <dt> @postcond</dt>
         <dd> Peut être utilisée pour les post-conditions formelles de
 cette fonction. Conseillée pour des fonctions de bibliothèques
 publiques.</dd>
         <dt> @precond</dt>
         <dd> Peut être utilisée pour des préconditions formelles de
 cette fonction. Conseillée pour des fonctions de bibliothèques
 publiques.</dd>
         <dt> @return</dt>
         <dd> Décrit les valeurs de retour de la fonction. </dd>
         <dt> @tpl|param &lt;TplParameterName&gt;</dt>
         <dd> Uniquement pour des modèles. Décrit un paramètre de
 modèle:
 signification, conditions, restrictions.<br>
 Une balise pour chaque paramètre de modèle.</dd>
       </dl>
       <h5> Balises spéciales pour Variables</h5>
       <dl>
         <dt> @dyn</dt>
         <dd>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.<br>
         </dd>
         <dt> @life|cycle</dt>
         <dd> Décrit le moment de la création et de la destruction d'une
 variable.</dd>
         <dt> @multi|plicity &lt;Plage&gt;</dt>
         <dd> La plage peut être quelque chose du genre “1+”, “0+”,
 “2..5”, “ jusqu'à 255 caractères ”.</dd>
       </dl>
       <h5> Balises Globales </h5>
       <dl>
         <dt><a name="at_html"></a> @HTML</dt>
         <dd> Valable pour le reste du fichier code source (ou jusqu'à
 la prochaine balise <a
  href="../Labo/fran%E7ais/HowToWriteDocumentation-Cpp_fr.html#at_nohtml">
 @NOHTML</a> ), les balises HTML dans la documentation seront reconnues
 en tant que telles.</dd>
         <dt><a name="at_nohtml"></a> @NOHTML</dt>
         <dd> Valable pour le reste du fichier code source (ou jusqu'à
 la prochaine balise <a
  href="../Labo/fran%E7ais/HowToWriteDocumentation-Cpp_fr.html#at_html">
 @HTML</a> ), les balises HTML dans la documentation seront ignorées et
 considérées comme du texte normal, c-à-d. ne seront pas traduites.</dd>
       </dl>
       <br>
       <dl>
         <dt>[DEBUT -&nbsp; N'EST VALABLE QU'A PARTIR DE: Autodoc
 Version 2.3, attendue en juillet 2002 ]<br>
           <a name="at_file"></a> @file</dt>
         <dd>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). <br>
 Tout texte suivant est traité comme s'il était au début du paragraphe
 de documentation . Voir aussi <a
  href="../Labo/fran%E7ais/HowToWriteDocumentation-Cpp_fr.html#typic">
 Commentaire Type de Documentation</a> La documentation après @file
 appartient au fichier, dans lequel elle est écrite.<br>
 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.</dd>
         <dt><a name="at_glos"></a> @glos|sary &lt;TermeDécrit&gt;</dt>
         <dd>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.<br>
 Le terme décrit ne peut qu'être constitué de caractères alphanumériques
 ( [A-Za-z0-9]+ ) .</dd>
         <dt> @glos|sary &lt;TermeDécrit&gt; &lt;LienHypertexte&gt;</dt>
         <dd> 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.<br>
 Le terme décrit ne peut qu'être constitué de caractères alphanumériques
 ( [A-Za-z0-9]+ ) .</dd>
         <dt><a name="at_namespace"></a> @namespace
 &lt;EspaceNomPleinementQualifié&gt;</dt>
         <dd> 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é</dd>
       </dl>
 [FIN - N'EST VALABLE QU'A PARTIR DE : Autodoc Version 2.3]<br>
       <br>
       <h5><a name="typic"></a> Commentaire Type de Documentation</h5>
       <pre>/** Bref Commentaire: Ceci est pour .... .<br>    <br>    Après une ligne vide, voici la description principale de l'entité de code. Ici on peut inclure un texte plus long, des exemples, <br>    des considérations philosophiques et des descriptions de solutions spéciales. <br>    On ne peut utiliser que des balises  @-tags après ce texte. Chaque texte suivant appartient à la balise qui précède @-tag. <br>    <br>    @param integer1 [0 .. 255]<br>    Describe parameter integer1.<br>    <br>    @param str2 <br>    Describe the parameter str2.<br><br>    @return true, if everything is ok. Else false.<br>*/<br>bool   funct_00( int integer1, const char * str2 );<br><br><br>[DEBUT - VALIDE SEULEMENT A PARTIR DE: Autodoc Version 2.3, attendue Juillet 2002 ]<br></pre>
       <h5><a name="link"></a> Liens Automatiques</h5>
 Certains mots dans les textes de documentation sont interpretés de
 manière automatique en tant que lien vers une entité de code.<br>
       <p> 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 "<tt>()</tt> ".<br>
       </p>
       <p> 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 "<tt> ::</tt>
 ". Ici encore, les fonctions doivent se terminer en "<tt>()</tt>".</p>
       <p>Bien entendu, la reconnaissance de tels noms est sensible à la
 casse et
 aux formes plurielles. Ils doivent être écrits exactement tels qu'ils
 sont.</p>
 [FIN - N'EST VALABLE QU'A PARTIR DE : Autodoc Version 2.3]<br>
       <br>
 Traduction Alex Thurgood<br>
       <br>
       <a style="font-family: helvetica,arial,sans-serif;"
  href="indexlabo.html">Retour à l'index Labo</a> <br>
       <span
  style="font-weight: bold; font-family: helvetica,arial,sans-serif; color: rgb(255, 255, 255);"></span><!-- /Table Navigation Bar -->
       <br>
       </td>
     </tr>
     <tr>
       <td align="right" valign="bottom">
       <p>&nbsp;</p>
 <!-- Copyrights -->
       <p><small>OpenOffice.org native tongue concept and francophone
 project are built for you with pride by Guy Capra (Alomphega).<br>
 This fr project is also led and maintained by Sophie Gautier.</small></p>
 <!-- /Copyrights --> </td>
     </tr>
   </tbody>
 </table>
 <br>
 <br>
 <br>
 <br>
 <br>
 <br>
 </body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
	<html>
	<head>
	<title>Labo</title>
	<meta http-equiv="content-type" content="text/html; charset=UTF-8">
	</head>
	<body>
	<table border="0" cellpadding="4" width="100%">
	<tbody>
	<tr>
	<td align="left" valign="top" width="100%"><!-- Content -->
	<div align="center">
	<h3 style="text-align: left;">Comment écrire de la Documentation
	de Code Source en C++</h3>
	<div align="right"><b> Dernière mise à jour: 29.5.2003</b><br>
	</div>
	<div align="right">
	<p><font size="3"><b>Contact: </b><a
	href="mailto:nikolai@sun.com"> Nikolai Pretzell</a> </font><br>
	</p>
	</div>
	</div>
	<h3>Scope</h3>
	<p>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.<br>
	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.<br>
	<br>
	</p>
	<h3>Règles de Base</h3>
	<ul>
	<li>
	<p>Il y a deux manières d'inclure de la documentation dans un
	fichier C++ :<br>
	De la documentation sur plusieurs lignes commencent par <span style=""><font
	face="Courier New, monospace"> /**</font></span> et se termine en <span
	style=""><font face="Courier New, monospace"> */</font></span> et
	ressemble donc à ceci: </p>
	<pre>/** un peu de texte<br> .................<br> .................<br>*/</pre>
	<p> De la documentation sur une seule ligne ou “intégrée en
	ligne” commence par <font face="Courier New, monospace"> /// </font>
	et se termine par la fin de la ligne, et prend donc cette forme : </p>
	<pre>/// un peu de texte .......<br></pre>
	<p>A “paragraphe de documentation” on peut utiliser l'une
	quelconque des méthodes décritrent ci-dessus. </p>
	</li>
	<li> Le langage de la documentation est l'anglais.</li>
	<li>Pour l'instant, seuls les fichiers d'en-tête sont traités
	par Autodoc.</li>
	<li>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.</li>
	</ul>
	<h3>Qu'est-ce qu'on peut documenter ?</h3>
	<p>Les entités de code pouvant faire l'objet d'une documentation
	en C++ sont: </p>
	<ul>
	<li>les classes (y compris les structs et unions)</li>
	<li>les enums</li>
	<li>les fonctions / méthodes</li>
	<li>les variables (y compris les constantes)</li>
	<li>les valeurs enum </li>
	<li>les #define-s </li>
	<li>les macro #define-d. </li>
	</ul>
	<p>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.</p>
	<p><br>
	[DEBUT  - N'EST VALABLE QU'A PARTIR DE : Autodoc Version 2.3,
	attendue en juillet 2002 ]<br>
	</p>
	<p> 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 :</p>
	<ul>
	<li>les classes de base</li>
	<li>les paramètres de fonction</li>
	<li>les valeurs enum.</li>
	</ul>
	<p>On ne peut utiliser qu'une virgule '<tt>,</tt>' 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 <tt>///
	. 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.</tt></p>
	<p> Les éléments suivants peuvent également faire l'objet d'une
	documentation:<br>
	</p>
	<ul>
	<li>les espaces de noms</li>
	<li> les fichiers de code source</li>
	<li> les termes d'un glossaire</li>
	</ul>
	<p>Pour les détails, voir les balises <a
	href="../Labo/fran%E7ais/HowToWriteDocumentation-Cpp_fr.html#at_namespace">@namespace</a>
	, <a
	href="../Labo/fran%E7ais/HowToWriteDocumentation-Cpp_fr.html#at_file">@file</a>
	et <a
	href="../Labo/fran%E7ais/HowToWriteDocumentation-Cpp_fr.html#at_glos">@glossary</a>
	ci-dessous.</p>
	<p>[FIN - N'EST VALABLE QU'A PARTIR DE : Autodoc Version 2.3 ]<br>
	<br>
	</p>
	<h3>Mise en page</h3>
	<p>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 <a
	href="../Labo/fran%E7ais/HowToWriteDocumentation-Cpp_fr.html#at_short">@short</a>
	, si elle ne dépasse pas les deux lignes et est suivie d'une ligne vide.<br>
	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 <a
	href="../Labo/fran%E7ais/HowToWriteDocumentation-Cpp_fr.html#at_descr">
	@descr</a> .</p>
	<p>La mise en page suivante est obligatoire :</p>
	<ul>
	<li>Des entrées commençant par '*'s ou '#'s dans chaque ligne
	de documentation ne doivent pas être utilsées! </li>
	<li>Toutes les balises @-tags doivent être les premiers
	éléments ne
	constituant pas d'espaces blancs dans leur ligne, sauf au <tt>/**
	début </tt>d'un paragraphe de documentation.</li>
	</ul>
	<p>La mise en page suivante est recommandée:</p>
	<ul>
	<li>Utilisation de la documentation à plusieurs lignes
	(/*.../).</li>
	<li> Commencez la documentation sur la même ligne que
	les <tt> /**</tt> .</li>
	<li> Les signes de début et de fin ( <tt>/**</tt> et <tt>
	*/</tt> ) d'un début de documentation à lignes multiples sont placés
	dans la même colonne
	que l'entité de code documenté.</li>
	<li> Chaque ligne et chaque balise font débuter 4 colonnes à la
	droite des signes de début et de fin (“/** et */”). </li>
	</ul>
	<p>Les balises HTML peuvent être utilisées en option.<br>
	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.<br>
	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 <a
	href="../Labo/fran%E7ais/HowToWriteDocumentation-Cpp_fr.html#at_html">
	@HTML</a> et <a
	href="../Labo/fran%E7ais/HowToWriteDocumentation-Cpp_fr.html#at_nohtml">@NOHTML</a>
	. 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.<br>
	Il n'est pas nécessaire d'utiliser du HTML pour générer les liens, dans
	la plupart des cas. Voir également <a
	href="../Labo/fran%E7ais/HowToWriteDocumentation-Cpp_fr.html#link">
	Liens Automatiques.</a> <br>
	</p>
	<h3>Balises</h3>
	Légende:<br>
	<blockquote>
	<dl>
	<dt>Un '\|' se trouvant dans une balise </dt>
	<dd>signifie que la balise peut être raccourcie à cette
	position.<br>
	</dd>
	<dt>Des mots se trouvant dans la même ligne que la balise
	@-tag</dt>
	<dd> sont des paramètres de celle-ci.</dd>
	<dt> <ABC></dt>
	<dd>un paramètre</dd>
	<dt>>>Xyz<<</dt>
	<dd>Xyz sera interpreté comme un <a
	href="../Labo/fran%E7ais/HowToWriteDocumentation-Cpp_fr.html#link">lien
	automatique</a> <br>
	</dd>
	<dt> "par" </dt>
	<dd> paramètres se trouvant entre "" est à prendre à la
	lettre. </dd>
	<dt>[...] </dt>
	<dd>Des paramètres se trouvant entre [] sont optionnels.</dd>
	<dt>NOTEXT</dt>
	<dd>Il ne peut y avoir de texte supplémentaire à cette
	balise. </dd>
	</dl>
	</blockquote>
	<p>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. </p>
	<pre>balise paramètre requis [paramètre optionnel]<br></pre>
	<h5>Balises pour toutes les entités de code</h5>
	<dl>
	<dt>@ATT\|ENTION</dt>
	<dd>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.</dd>
	<dt>@author <Un.Nom></dt>
	<dd>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.<br>
	NOTEXT.</dd>
	<dt>@change <dd.mm.yyyy> "par"
	<Quiafaitlechangement></dt>
	<dd>Il doit y avoir une nouvelle balise @change pour chaque
	changement, la plus récente en première.</dd>
	<dt>@deprecated</dt>
	<dd>Identifie une entité de code comme n'existant que pour la
	rétrocompatibilité.<br>
	NOTEXT</dd>
	<dt><a name="at_descr"></a> @descr</dt>
	<dd>Le texte principal décrivant l'entité documentée.<br>
	La balise peut être omise avant ce texte (voir <a
	href="../Labo/fran%E7ais/HowToWriteDocumentation-Cpp_fr.html#typic">
	Commentaire Type sur la Documentation</a> ).</dd>
	<dt>@docdate <dd.mm.yyyy></dt>
	<dd>Date de la documentation. La dernière date à laquelle la
	documentation a été modifiée.<br>
	NOTEXT.</dd>
	<dt>@empty</dt>
	<dd>Balise spéciale pour la documentation qui a été testée.
	Cela veut dire, ici, qu'aucune documentation n'est voulue.<br>
	<p><b>@@@@Je ne comprends pas ce que ceci est supposé faire...</b></p>
	NOTEXT.<br>
	</dd>
	<dt>@internal</dt>
	<dd>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.<br>
	NOTEXT.</dd>
	<dt>@key <MotClé></dt>
	<dd>Cette balise
	donne la possibilité de rechercher dans la documentation créée ou de la
	filtrer, avec la clé donnée.<br>
	Une balise pour chaque clé. <br>
	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.<br>
	NOTEXT.</dd>
	<dt>@see\|also >>AVoir<<</dt>
	<dd>Cette balise pointe vers une entité de code liée. <br>
	NOTEXT.</dd>
	<dt><a name="at_short"></a> @short</dt>
	<dd>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.<br>
	La balise peut être omise avant ce texte (voir <a
	href="../Labo/fran%E7ais/HowToWriteDocumentation-Cpp_fr.html#typic">
	Commentaire Type sur la Documentation</a> ).</dd>
	<dt> @todo</dt>
	<dd> Tâches qui ne sont pas encore accomplies par rapport à une
	entité de code.</dd>
	</dl>
	<h5> Balises spéciales pour des Classes</h5>
	<dl>
	<dt> @base >>ClassedeBase<<</dt>
	<dd> Commentaire d'une classe de base. <br>
	A n'utiliser que s'il y a des commentaires. Le listage simple
	de classes de base est fait de manière automatique.</dd>
	<dt> @collab\|orator >>LeCollaborateur<<</dt>
	<dd> >Ceci est utilisé dans le sens des Cartes CRC <a
	href="http://c2.com/cgi/wiki?CrcCards"> </a> .<br>
	Une balise pour chaque collaborateur.</dd>
	<dt> @derive</dt>
	<dd>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.</dd>
	<dt> @instance <NomObjet></dt>
	<dd> Décrit une instance spécifique de cette classe.<br>
	Une balise pour chaque instance.</dd>
	<dt> @interface</dt>
	<dd> 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.<br>
	NOTEXT.</dd>
	<dt> @invariant</dt>
	<dd> Celle-ci peut être utilisée pour des invariables formels
	de cette classe. Elle est conseillée pour des classes/interfaces
	utilisées publiquement.</dd>
	<dt> @resp\|onsibility </dt>
	<dd> Celle-ci doit être utilisée dans le sens des Cartes CRC <a
	href="http://c2.com/cgi/wiki?CrcCards"> </a> .<br>
	Une balise pour chaque responsabilité.</dd>
	<dt> @tpl\|param <TplParamName></dt>
	<dd> Uniquement pour des modèles. Décrit un paramètre de
	modèle:
	signification, conditions, restrictions.<br>
	Une balise pour chaque paramètre de modèle.<br>
	</dd>
	</dl>
	<h5> Balises spéciales pour fonctions/méthodes</h5>
	<dl>
	<dt> @exception >>TypeException<<</dt>
	<dd> Décrit une exception.<br>
	Une balise pour chaque exception.<br>
	A n'utiliser que s'il y a des commentaires. Le listage
	simple d'exceptions est fait de manière automatique.</dd>
	<dt> @invariant</dt>
	<dd> Peut être utilisée pour des invariables formels de la
	fonction. </dd>
	<dt> @onerror</dt>
	<dd> Gestion des exceptions. Peut être utilisée si aucune
	spécification d'exception n'est faite.</dd>
	<dt> @param <NomParamètre> [ "["<PlageValide> "]" ]</dt>
	<dd> Décrit un paramètre de fonction. <br>
	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).<br>
	Une balise pour chaque paramètre.<br>
	A n'utiliser que s'il y a des commentaires. Le listage simple
	de paramètres se fait de manière automatique.</dd>
	<dt> @postcond</dt>
	<dd> Peut être utilisée pour les post-conditions formelles de
	cette fonction. Conseillée pour des fonctions de bibliothèques
	publiques.</dd>
	<dt> @precond</dt>
	<dd> Peut être utilisée pour des préconditions formelles de
	cette fonction. Conseillée pour des fonctions de bibliothèques
	publiques.</dd>
	<dt> @return</dt>
	<dd> Décrit les valeurs de retour de la fonction. </dd>
	<dt> @tpl\|param <TplParameterName></dt>
	<dd> Uniquement pour des modèles. Décrit un paramètre de
	modèle:
	signification, conditions, restrictions.<br>
	Une balise pour chaque paramètre de modèle.</dd>
	</dl>
	<h5> Balises spéciales pour Variables</h5>
	<dl>
	<dt> @dyn</dt>
	<dd>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.<br>
	</dd>
	<dt> @life\|cycle</dt>
	<dd> Décrit le moment de la création et de la destruction d'une
	variable.</dd>
	<dt> @multi\|plicity <Plage></dt>
	<dd> La plage peut être quelque chose du genre “1+”, “0+”,
	“2..5”, “ jusqu'à 255 caractères ”.</dd>
	</dl>
	<h5> Balises Globales </h5>
	<dl>
	<dt><a name="at_html"></a> @HTML</dt>
	<dd> Valable pour le reste du fichier code source (ou jusqu'à
	la prochaine balise <a
	href="../Labo/fran%E7ais/HowToWriteDocumentation-Cpp_fr.html#at_nohtml">
	@NOHTML</a> ), les balises HTML dans la documentation seront reconnues
	en tant que telles.</dd>
	<dt><a name="at_nohtml"></a> @NOHTML</dt>
	<dd> Valable pour le reste du fichier code source (ou jusqu'à
	la prochaine balise <a
	href="../Labo/fran%E7ais/HowToWriteDocumentation-Cpp_fr.html#at_html">
	@HTML</a> ), les balises HTML dans la documentation seront ignorées et
	considérées comme du texte normal, c-à-d. ne seront pas traduites.</dd>
	</dl>
	<br>
	<dl>
	<dt>[DEBUT -  N'EST VALABLE QU'A PARTIR DE: Autodoc
	Version 2.3, attendue en juillet 2002 ]<br>
	<a name="at_file"></a> @file</dt>
	<dd>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). <br>
	Tout texte suivant est traité comme s'il était au début du paragraphe
	de documentation . Voir aussi <a
	href="../Labo/fran%E7ais/HowToWriteDocumentation-Cpp_fr.html#typic">
	Commentaire Type de Documentation</a> La documentation après @file
	appartient au fichier, dans lequel elle est écrite.<br>
	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.</dd>
	<dt><a name="at_glos"></a> @glos\|sary <TermeDécrit></dt>
	<dd>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.<br>
	Le terme décrit ne peut qu'être constitué de caractères alphanumériques
	( [A-Za-z0-9]+ ) .</dd>
	<dt> @glos\|sary <TermeDécrit> <LienHypertexte></dt>
	<dd> 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.<br>
	Le terme décrit ne peut qu'être constitué de caractères alphanumériques
	( [A-Za-z0-9]+ ) .</dd>
	<dt><a name="at_namespace"></a> @namespace
	<EspaceNomPleinementQualifié></dt>
	<dd> 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é</dd>
	</dl>
	[FIN - N'EST VALABLE QU'A PARTIR DE : Autodoc Version 2.3]<br>
	<br>
	<h5><a name="typic"></a> Commentaire Type de Documentation</h5>
	<pre>/** Bref Commentaire: Ceci est pour .... .<br> <br> Après une ligne vide, voici la description principale de l'entité de code. Ici on peut inclure un texte plus long, des exemples, <br> des considérations philosophiques et des descriptions de solutions spéciales. <br> On ne peut utiliser que des balises @-tags après ce texte. Chaque texte suivant appartient à la balise qui précède @-tag. <br> <br> @param integer1 [0 .. 255]<br> Describe parameter integer1.<br> <br> @param str2 <br> Describe the parameter str2.<br><br> @return true, if everything is ok. Else false.<br>/<br>bool funct_00( int integer1, const char str2 );<br><br><br>[DEBUT - VALIDE SEULEMENT A PARTIR DE: Autodoc Version 2.3, attendue Juillet 2002 ]<br></pre>
	<h5><a name="link"></a> Liens Automatiques</h5>
	Certains mots dans les textes de documentation sont interpretés de
	manière automatique en tant que lien vers une entité de code.<br>
	<p> 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 "<tt>()</tt> ".<br>
	</p>
	<p> 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 "<tt> ::</tt>
	". Ici encore, les fonctions doivent se terminer en "<tt>()</tt>".</p>
	<p>Bien entendu, la reconnaissance de tels noms est sensible à la
	casse et
	aux formes plurielles. Ils doivent être écrits exactement tels qu'ils
	sont.</p>
	[FIN - N'EST VALABLE QU'A PARTIR DE : Autodoc Version 2.3]<br>
	<br>
	Traduction Alex Thurgood<br>
	<br>
	<a style="font-family: helvetica,arial,sans-serif;"
	href="indexlabo.html">Retour à l'index Labo</a> <br>
	<span
	style="font-weight: bold; font-family: helvetica,arial,sans-serif; color: rgb(255, 255, 255);"></span><!-- /Table Navigation Bar -->
	<br>
	</td>
	</tr>
	<tr>
	<td align="right" valign="bottom">
	<p> </p>
	<!-- Copyrights -->
	<p><small>OpenOffice.org native tongue concept and francophone
	project are built for you with pride by Guy Capra (Alomphega).<br>
	This fr project is also led and maintained by Sophie Gautier.</small></p>
	<!-- /Copyrights --> </td>
	</tr>
	</tbody>
	</table>
	<br>
	<br>
	<br>
	<br>
	<br>
	<br>
	</body>
	</html>