Bonnes pratiques de documentation C

• Les membres publics doivent être documentés avec des commentaires XML.
• Il est recommandé de documenter aussi les membres internes, en particulier s'ils sont complexes ou pas évidents à comprendre.

Recommandations pour toutes les API

• Utilisez <summary> pour fournir une brève description d'une seule phrase de ce que le type ou le membre fait. Commencez le résumé par un verbe au présent à la troisième personne.
• Utilisez <remarks> pour des informations supplémentaires, qui peuvent inclure des détails d'implémentation, des notes d'utilisation ou tout autre contexte pertinent.
• Utilisez <see langword> pour les mots-clés spécifiques au langage comme null, true, false, int, bool, etc.
• Utilisez <c> pour les extraits de code en ligne.
• Utilisez <example> pour des exemples d'utilisation montrant comment utiliser le membre.
  • Utilisez <code> pour les blocs de code. Les balises <code> doivent être placées dans une balise <example>. Ajoutez le langage de l'exemple de code à l'aide de l'attribut language, par exemple <code language="csharp">.
• Utilisez <see cref> pour référencer d'autres types ou membres en ligne (dans une phrase).
• Utilisez <seealso> pour les références autonomes (pas dans une phrase) à d'autres types ou membres dans la section « Voir aussi » de la documentation en ligne.
• Utilisez <inheritdoc/> pour hériter la documentation des classes de base ou des interfaces.
  • Sauf s'il y a un changement de comportement majeur, auquel cas vous devez documenter les différences.

Méthodes

• Utilisez <param> pour décrire les paramètres de méthode.
  • La description doit être une phrase nominale qui ne précise pas le type de données.
  • Commencez par un article d'introduction.
  • Si le paramètre est une énumération de drapeaux, commencez la description par « Une combinaison au niveau du bit des valeurs d'énumération qui spécifie... ».
  • Si le paramètre est une énumération sans drapeaux, commencez la description par « L'une des valeurs d'énumération qui spécifie... ».
  • Si le paramètre est booléen, la formulation doit être de la forme « <see langword="true" /> pour... ; sinon, <see langword="false" />. ».
  • Si le paramètre est un paramètre « out », la formulation doit être de la forme « Quand cette méthode retourne, contient.... Ce paramètre est considéré comme non initialisé. ».
• Utilisez <paramref> pour référencer les noms de paramètres dans la documentation.
• Utilisez <typeparam> pour décrire les paramètres de type dans les types ou méthodes génériques.
• Utilisez <typeparamref> pour référencer les paramètres de type dans la documentation.
• Utilisez <returns> pour décrire ce que la méthode retourne.
  • La description doit être une phrase nominale qui ne précise pas le type de données.
  • Commencez par un article d'introduction.
  • Si le type de retour est booléen, la formulation doit être de la forme « <see langword="true" /> si... ; sinon, <see langword="false" />. ».

Constructeurs

• La formulation du résumé doit être « Initialise une nouvelle instance de la classe [ou struct] <Class>. ».

Propriétés

• Le <summary> doit commencer par :
  • « Obtient ou définit... » pour une propriété en lecture-écriture.
  • « Obtient... » pour une propriété en lecture seule.
  • « Obtient [ou définit] une valeur qui indique si... » pour les propriétés qui retournent une valeur booléenne.
• Utilisez <value> pour décrire la valeur de la propriété.
  • La description doit être une phrase nominale qui ne précise pas le type de données.
  • Si la propriété a une valeur par défaut, ajoutez-la dans une phrase séparée, par exemple « La valeur par défaut est <see langword="false" /> ».
  • Si le type de valeur est booléen, la formulation doit être de la forme « <see langword="true" /> si... ; sinon, <see langword="false" />. La valeur par défaut est... ».

Exceptions

• Utilisez <exception cref> pour documenter les exceptions levées par les constructeurs, propriétés, indexeurs, méthodes, opérateurs et événements.
• Documentez toutes les exceptions levées directement par le membre.
• Pour les exceptions levées par des membres imbriqués, documentez uniquement les exceptions que les utilisateurs risquent le plus de rencontrer.
• La description de l'exception décrit la condition dans laquelle elle est levée.
  • Omettez « Levée si... » ou « Si... » au début de la phrase. Énoncez simplement la condition directement, par exemple « Une erreur s'est produite lors de l'accès à une API Message Queuing. »