Cette page est consultable pour des raisons historiques.

La documentation du code en C#

La documentation du code est particulièrement utile lors des évolutions et de la maintenance du code. C# propose un mécanisme simple pour insérer dans le code des commentaires de documentation qui seront traités pour réaliser une documentation technique.

Ces commentaires de documentation sont préfixés par ///

Ces commentaires sont saisis avant la déclaration des entités de type namespace, classe, interface, champ, propriété, méthode, ou événement.

Ces commentaires peuvent utiliser des tags XML pour caractériser certaines informations. Ces tags seront repris dans un document XML peut être généré à la demande par le compilateur. Il est donc important que les commentaires de documentation saisis respectent le standard XML.

Ce fichier XML peut ensuite être traité pour par exemple produire des pages HTML grâce à une feuille de style XSLT.

Microsoft a défini une liste de tags particuliers recommandés mais il est tout à fait possible d'utiliser ces propres tags.

 

Les tags de documentation recommandés

Les tags XML suivants sont utilisables pour la documentation du code :

<c>	<code>	<example>
<exception>	<include>	<list>
<para>	<param>	<paramref>
<permission>	<remarks>	<return>
<see>	<seealso>	<summary>
<value>

Ces tags sont utilisables en fonction de l'entité documentée

Entité	Tags utilisables
class	<summary>, <remarks>, <seealso>
struct	<summary>, <remarks>, <seealso>
interface	<summary>, <remarks>, <seealso>
delegate	<summary>, <remarks>, <seealso>, <param>, <returns>
enum	<summary>, <remarks>, <seealso>
constructor	<summary>, <remarks>, <seealso>, <param>, <permission>, <exception>
property	<summary>, <remarks>, <seealso>, <value>, <permission>, <exception>
method	<summary>, <remarks>, <seealso>, <param>, <returns>, <permission>, <exception>
event	<summary>, <remarks>, <seealso>

 

Le tag <c>

Ce tag permet d'afficher le texte qu'il contient sous la forme de code

Syntaxe :

<c>texte</c>

Exemple :

/// resume de <c>maMethode</c>

 

Le tag <code>

Ce tag permet d'afficher le texte qu'il contient sous la forme de code. La différence avec le tag <c> est que que le tag <code> est utilisé en multi-ligne.

Syntaxe :

<code> 
ligne1
ligne2
</code>

Exemple

/// <code>
///   Class1 m = new Class1();
///   m.maMethode("Hello");
/// </code>

 

Le tag <example>

Ce tag permet de fournir un exemple d'utilisation de l'entité.

Syntaxe :

<example>
texte 
</example

Exemple :

/// <example> 
/// Mise en oeuvre : 
/// <code> 
///   Class1 m = new Class1();
///   m.maMethode("Hello");
/// </code> 
/// </example>

 

Le tag <exception>

Ce tag permet de fournir des informations sur la levée d'une exception par une méthode

 

Le tag <list>

Ce tag permet de créer une liste d'élément avec puce, ou numéroté ou sous forme de tableau.

Syntaxe :

  <list type="bullet" | "number" | "table">
     <listheader>
        <term>term</term>
        <description>description</description>
     </listheader>
     <item>
        <term>term</term>
        <description>description</description>
     </item> 
  </list>

 

Le tag <para>

Ce tag permet de créer un paragraphe à l'intérieur d'un tag.

Syntaxe

<para>texte</para>

 

Le tag <param>

Ce tag permet de fournir des informations sur un paramètre d'une méthode.

Syntaxe :

<param name='name'>description</param>

L'attribut name permet de préciser le nom du paramètre.

Exemple :

/// <param name="nom">nom de l'utilisateur</param>

 

Le tag <paramref>

Ce tag permet de faire référence à un paramètre dans le texte

Syntaxe :

<paramref name="name"/>

 

Le tag <remarks>

Ce tag permet de fournir des informations complémentaires sur une entité sous la forme d'une remarque.

Syntaxe :

<remarks>description</remarks>

Exemple :

/// <remarks>remarque complémentaire.</remarks>

 

Le tag <return>

Ce tag permet de fournir de informations sur la valeur de retour d'une méthode

Syntaxe :

<returns>description</returns>

Exemple :

/// <returns>une chaine contenant une salutation</returns>

 

Le tag <see>

Ce tag permet de faire un lien vers un élément accessible dans le code.

Syntaxe :

<see cref="member"/>

L'attribut cref permet de préciser le membre.

Exemple :

/// <see cref="maMethode" />

Le compilateur vérifie l'accessibilité du membre précisé dans l'attribut cref : si celle ci échoué, il émet un avertissement

Exemple :

Le commentaire XML sur 'ClassLibrary.Class1.maMethode(string)' possède l'attribut 
cref 'maMethode2df' et celui-ci est introuvable

 

Le tag <seealso>

Ce tag permet de faire un lien vers un élément qui sera inclus dans la section see also.

Syntaxe :

<seealso cref="member"/>

L'attribut cref permet de préciser le membre.

Exemple :

///  <seealso cref="ClassLibrary.MaCLasse2"/>

 

Le tag <summary>

Ce tag permet de fournir un résumé d'une entité.

Syntaxe

<summary>description</summary>

Exemple :

/// <summary>
/// resume de maMethode
/// </summary>

Le contenu de ce tag est utilisé par la fonction Intellisens de Visual Studio .Net pour afficher des informations sur l'entité.

 

Le tag <value>

Ce tag permet de fournir des informations sur une propriété

Syntaxe :

<value>description</value>

Exemple :

/// <value>  valeur entiere utilise dans les calculs 
/// </value>

 

Mise en ouvre avec Visual Studio .Net

 

Saisie des commentaires de documentation

Il suffit de saisir /// sur la ligne avant la déclaration de l'entité pour que Visual Studio .Net génère automatiquement un squelette de commentaire de documentation en tenant compte de la déclaration de l'entité.

 

Configuration du projet

Dans les propriétés du projet, sélectionner " Propriétés de configuration / générer " et modifier la propriété " Fichier de documentation XML "

Il suffit de préciser un nom de fichier qui par convention se nomme nom_du_projet.xml.

A la compilation, ce fichier XML sera regénéré à partir du code source

Exemple :

<?xml version="1.0"?>
  <doc>
      <assembly>
          <name>ClassLibrary</name>
      </assembly>
      <members>
          <member name="T:ClassLibrary.Class1">
              <summary>
              Description resume de Class1.
              </summary>
          </member>
          <member name="M:ClassLibrary.Class1.maMethode(System.String)">
              <summary>
              resume de maMethode
              </summary>
              <param name="nom">nom de l'utilisateur</param>
              <returns>une chaine contenant une salutation</returns>
          </member>
      </members>
  </doc>

 

Utilisation de la documentation par V.S. .Net

Ce fichier va être utilisé par Visual Studio .Net pour fournir des informations dans l'éditeur de code.

Exemple : lors de la sélection d'une méthode

Exemple : lors de sélection de la saisie d'un paramètre

L'inconvénient sous V.S. .Net une fois le fichier xml de documentation précisé pour un projet est qu'il faut définir un commentaire de documentation pour toutes les entités du projet ainsi que leur membre, sinon un avertissement est signalé pour chaque élément qui n'en possède pas.

 

Génération de la documentation au format Web

A partir du fichier XML, V.S. .Net peut générer la documentation sous la forme de page HTML : un rapport Web de commentaire de code.

Pour demander la génération de la documentation au format HTML, il faut utiliser l'option " Générer les pages web de documentation . " du menu " Outils ".

La boîte de dialogue permet de sélectionner les éléments pour lesquels la documentation doit être généré, l'emplacement ou elle doit être stockée et des options.

Les pages web générées proposent un système de navigation dans les différents éléments commentés.

 

L'outils NDoc

Microsoft ne propose pas d'outils satisfaisant pour exploiter les fichiers de documentations XML générés par le compilateur C#.

Le projet open source NDoc propose une solution pour générer à partir de fichiers XML, une documentation dans plusieurs formats grâce à des feuilles de style XSLT  : HtmlHelp2, Javadoc et MDSN. Deux autres formats sont proposés à titre expérimental (version 1.2.1303).

Le site web du projet se trouve à l'url : http://ndoc.sourceforge.net

Pour fonctionner l'outils HTML Help Workshop doit être installé sur la machine. il est livré avec plusieurs outils de développement dont Visual Studio .Net ou peut être téléchargé indépendament sur le site de Microsoft.

Pour lancer NDoc, il suffit d'exécuter l'application NDocGui.exe

Il faut ajouter un ou plusieurs assemblys en cliquant sur le bouton " add "

Il est aussi possible de laisser NDoc analyser directement une solution de Visual Studio .Net en cliquant sur le bouton ou en utilisant l'option " New from Visual Studio Solution ". Il suffit alors de sélectionner le fichier .sln.

Il faut ensuite s"lectionner le type de documentation dans la liste d"roulante.

Un certain nombre de paramètres peuvent être renseignés pour paramétrer la génération en fonction du type de documentation demandée.

Pour demander la génération, il suffit de cliquer sur le bouton ou d'utiliser l'option " Build " du menu " Documentation " ou enfin d'utiliser la combinaison de touche Ctrl+Maj+B.