Comment : utiliser les fonctionnalités de la documentation XML (Guide de programmation C#)

La documentation XML offre un moyen efficace pour documenter votre code. L'exemple suivant présente une vue d'ensemble de base.

Exemple

// If compiling from the command line, compile with: /doc:YourFileName.xml

/// <summary>
/// Class level summary documentation goes here.</summary>
/// <remarks>
/// Longer comments can be associated with a type or member through
/// the remarks tag.</remarks>
public class TestClass : TestInterface
{
    /// <summary>
    /// Store for the name property.</summary>
    private string _name = null;

    /// <summary>
    /// The class constructor. </summary>
    public TestClass()
    {
        // TODO: Add Constructor Logic here.
    }

    /// <summary>
    /// Name property. </summary>
    /// <value>
    /// A value tag is used to describe the property value.</value>
    public string Name
    {
        get
        {
            if (_name == null)
            {
                throw new System.Exception("Name is null");
            }
            return _name;
        }
    }

    /// <summary>
    /// Description for SomeMethod.</summary>
    /// <param name="s"> Parameter description for s goes here.</param>
    /// <seealso cref="System.String">
    /// You can use the cref attribute on any tag to reference a type or member 
    /// and the compiler will check that the reference exists. </seealso>
    public void SomeMethod(string s)
    {
    }

    /// <summary>
    /// Some other method. </summary>
    /// <returns>
    /// Return results are described through the returns tag.</returns>
    /// <seealso cref="SomeMethod(string)">
    /// Notice the use of the cref attribute to reference a specific method. </seealso>
    public int SomeOtherMethod()
    {
        return 0;
    }

    public int InterfaceMethod(int n)
    {
        return n * n;
    }

    /// <summary>
    /// The entry point for the application.
    /// </summary>
    /// <param name="args"> A list of command line arguments.</param>
    static int Main(System.String[] args)
    {
        // TODO: Add code to start application here.
        return 0;
    }
}

/// <summary>
/// Documentation that describes the interface goes here.
/// </summary>
/// <remarks>
/// Details about the interface go here.
/// </remarks>
interface TestInterface
{
    /// <summary>
    /// Documentation that describes the method goes here.
    /// </summary>
    /// <param name="n">
    /// Parameter n requires an integer argument.
    /// </param>
    /// <returns>
    /// The method returns an integer.
    /// </returns>
    int InterfaceMethod(int n);
}

Le fichier .xml suivant est généré par l'exemple précédent. Notez que les commentaires de la définition d'interface sont inclus dans la classe qui implémente l'interface.

Compilation du code

Pour compiler l'exemple, vous pouvez taper la ligne de commande suivante : csc XMLsample.cs /doc:XMLsample.xml.

Cette commande crée le fichier XML XMLsample.xml, que vous pouvez afficher dans un navigateur ou dans un traitement de texte.

Vous pouvez également cliquer avec le bouton droit sur le nom du projet dans l'Explorateur de solutions, puis sur Propriétés. Dans l'onglet Build, sélectionnez Fichier de documentation XML dans la section Sortie, puis entrez un nom pour le fichier .xml.

Programmation fiable

La documentation XML commence par ///. Lorsque vous créez un projet, l'IDE ajoute quelques lignes /// pour vous. Le traitement de ces commentaires s'accompagne des restrictions suivantes :

• Le XML utilisé dans la documentation doit être correct. Si le XML n'est pas correct, un avertissement est généré et le fichier de documentation contient un commentaire indiquant qu'une erreur a été détectée.

• Les développeurs peuvent créer leurs propres groupes de balises. Toutefois, il existe un jeu de balises recommandé (consultez la section voir aussi de cette rubrique) qui ont des significations particulières, comme indiqué dans les exemples suivants :

  • La balise <param> est employée pour décrire les paramètres. Si elle est utilisée, le compilateur vérifie que les paramètres existent et que tous les paramètres sont décrits dans la documentation. Si la vérification échoue, il émet un avertissement.

  • L'attribut cref peut être rattaché à n'importe quelle balise pour fournir une référence à un élément de code. Le compilateur vérifie l'existence de cet élément de code. Si la vérification échoue, il émet un avertissement. Le compilateur respecte les instructions using lorsqu'il recherche un type décrit dans l'attribut cref.

  • La balise <summary> est employée par IntelliSense dans Visual Studio pour afficher d'autres informations sur un type ou un membre.

    Notes

    Le fichier XML ne fournit pas d'informations complètes sur le type et les membres. Par exemple, il ne contient aucune information de type. Pour obtenir des informations complètes sur un type ou un membre, vous devez utiliser le fichier de documentation avec la réflexion sur le type ou le membre réel.

Voir aussi

Référence

/doc (Options du compilateur C#)

Commentaires de documentation XML (Guide de programmation C#)

Concepts

Guide de programmation C#

Historique des modifications

Date	Historique	Motif
Avril 2011	Une interface a été ajoutée à l'exemple.	Commentaires client.