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

Mise à jour : novembre 2007

L'exemple suivant propose une vue d'ensemble d'un type qui a été documenté.

Exemple

// compile with: /doc:DocFileName.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
{
    /// <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;
    }

    /// <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;
    }
}

// This .xml file was generated with the previous code sample.
<?xml version="1.0"?>
<doc>
    <assembly>
        <name>xmlsample</name>
    </assembly>
    <members>
        <member name="T:SomeClass">
            <summary>
            Class level summary documentation goes here.</summary>
            <remarks>
            Longer comments can be associated with a type or member 
            through the remarks tag</remarks>
        </member>
        <member name="F:SomeClass.m_Name">
            <summary>
            Store for the name property</summary>
        </member>
        <member name="M:SomeClass.#ctor">
            <summary>The class constructor.</summary> 
        </member>
        <member name="M:SomeClass.SomeMethod(System.String)">
            <summary>
            Description for SomeMethod.</summary>
            <param name="s"> Parameter description for s goes here</param>
            <seealso cref="T: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>
        </member>
        <member name="M:SomeClass.SomeOtherMethod">
            <summary>
            Some other method. </summary>
            <returns>
            Return results are described through the returns tag.</returns>
            <seealso cref="M:SomeClass.SomeMethod(System.String)">
            Notice the use of the cref attribute to reference a specific method </seealso>
        </member>
        <member name="M:SomeClass.Main(System.String[])">
            <summary>
            The entry point for the application.
            </summary>
            <param name="args"> A list of command line arguments</param>
        </member>
        <member name="P:SomeClass.Name">
            <summary>
            Name property </summary>
            <value>
            A value tag is used to describe the property value</value>
        </member>
    </members>
</doc>

Compilation du code

Pour compiler ce programme, tapez la ligne de commande suivante :

csc XMLsample.cs /doc:XMLsample.xml

Cette commande crée le fichier XML XMLsample.xml, que vous pouvez afficher soit dans votre navigateur soit en utilisant la commande TYPE.

Programmation fiable

La documentation XML commence par ///. Lorsque vous créez un nouveau projet, les Assistants insèrent automatiquement plusieurs lignes /// au début. Le traitement de ces commentaires s'accompagne de certaines restrictions :

• Le XML utilisé dans la documentation doit être correct. Si le XML n'est pas correct, un avertissement sera généré et le fichier de documentation contiendra un commentaire indiquant qu'une erreur est survenue.

• Les développeurs sont libres de créer leur propre jeu de balises. Il existe un jeu de balises recommandé (consultez la section Sources d'informations supplémentaires). Certaines des balises recommandées ont des significations spéciales :

  • La balise <param> est employée pour décrire les paramètres. Si elle est utilisée, le compilateur vérifiera que le paramètre existe et que tous les paramètres sont décrits dans la documentation. Si la vérification a échoué, 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érifiera l'existence de cet élément de code. Si la vérification a échoué, 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.

    Remarque :
    Le fichier XML ne fournit pas des 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

Tâches

Documentation XML, exemple

Concepts

Guide de programmation C#

Référence

/doc (Traiter les commentaires de documentation) (Options du compilateur C#)

Commentaires de documentation XML (Guide de programmation C#)