Programmation C sharp/Documentation XML des classes
Le langage C# permet de documenter les classes d'une application en utilisant des commentaires spéciaux juste avant la déclaration de l'élément concerné (espace de noms, classe, interface, méthode, propriété, attribut).
Syntaxe
modifierLes commentaires de documentation commencent par un triple slash /// et se termine au prochain retour à la ligne.
Le contenu de ces commentaires est au format XML. Il est possible d'utiliser plusieurs lignes.
Exemple :
/// <summary>
/// Une classe pour démontrer
/// les commentaires de documentation
/// </summary>
public class Exemple
{
...
}
Depuis la version 2003 du compilateur C# (pour la normalisation ECMA), il est également possible d'utiliser des blocs de commentaires /** ... */ :
/**
<summary>
Une classe pour démontrer
les commentaires de documentation
</summary>
*/
public class Exemple
{
...
}
Il est possible de mélanger les deux styles, mais non recommandé pour la lisibilité du code :
/**
<summary>
Une classe pour démontrer
les commentaires de documentation
*/
/// </summary>
public class Exemple
{
...
}
Générer la documentation
modifierLe compilateur C# est capable de générer un fichier XML à partir des fichiers sources.
| Windows | csc /doc:fichier.xml fichier_source.cs
|
| Linux (Mono) | gmcs -doc:fichier.xml fichier_source.cs
|
Exemple :
csc /doc:exemple.xml exemple.cs
Balises XML standards
modifierQuelques balises XML sont utilisées couramment. Les balises suivantes sont placées en dehors de toute autre :
<summary>- Description sommaire de l'entité (classe, méthode ou autre).
<remarks>- Remarque concernant l'entité décrite.
<value>- Description de la valeur d'une propriété.
<param name="nom_du_parametre">- Description du paramètre de la méthode.
<returns>- Description de la valeur retournée par la méthode.
<typeparam name="nom_du_parametre_type">- Description du paramètre type générique.
<seealso cref="membre">- Référence à une classe ou un de ses membres en relation avec l'entité décrite.
<exception cref="classe">- Décrit la classe d'exception lancée par la méthode : description de l'erreur, cas où l'exception est lancée, ...
<example>- Un exemple d'utilisation.
Les balises suivantes sont placées à l'intérieur de celles décrites ci-dessus pour formater le texte :
<para>- Paragraphe de texte.
<c>- Extrait de code.
<code>- Bloc de code.
<paramref name="nom_du_parametre"/>- Référence dans le texte à un paramètre de la méthode.
<typeparamref name="nom_du_parametre"/>- Référence dans le texte à un paramètre type générique.
<see cref="membre">- Référence dans le texte à une classe ou un de ses membres en relation avec l'entité décrite.
<list type="type_de_liste">- Une liste ou un tableau. type_de_liste peut valoir
bullet(liste non ordonnée),number(liste numérotée) outable(tableau).
Il est également possible d'ajouter ses propres balises XML.
La balise <list> contient les balises suivantes :
<listheader>- En-tête de tableau.
<item>- Ligne de tableau.
Ces balises contiennent :
<term>- Terme défini.
<description>- Description correspondante.
L'attribut cref peut en fait s'appliquer à toute balise XML pour faire référence à une autre entité (classe, méthode, propriété, ...).
Il est également possible d'utiliser un fichier XML séparé pour documenter plusieurs entités, en utilisant la balise include :
<include file="chemin_du_fichier_xml" path="chemin_XPath" />- Copier les balises XML spécifiées par le chemin XPath dans le fichier spécifié.
Visualiser la documentation
modifierVisualiser directement le fichier XML tel quel n'est pas très pratique. Il est possible d'utiliser des logiciels de visualisation spécialisés, ou bien d'utiliser un navigateur supportant XML et XSL (Internet Explorer et Firefox par exemple). Pour cela, plusieurs feuilles de style (stylesheet en anglais) sont téléchargeables depuis internet :
Puis il faut modifier le fichier XML produit en ajoutant la ligne suivante juste après la première balise <?xml ...?> :
<?xml-stylesheet type="text/xsl" href="''nom_du_fichier''.xsl"?>
En double-cliquant sur le fichier XML sous Windows, le navigateur applique la transformation décrite par la stylesheet indiquée pour afficher une version HTML plus présentable que le format initial.
Cependant la feuille de transformation fournie par MSDN comporte quelques problèmes :
- Les types génériques ne sont pas correctement présentés et laissés tel qu'ils sont dans le fichier XML initial : un ou deux apostrophes inversées indiquent le nombre ou l'indice des paramètres génériques.
Par exemple :Affiche``2(string, ``1, ``0)représenteAffiche<T0,T1>(string, <T1>, <T0>), - Les références dans les balises XML
seealsone sont pas affichées. Pour corriger ce problème, remplacercrefpar@crefdans la feuille de style :
<xsl:template match="seealso">
<xsl:if test="@cref">