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

L'exemple suivant fournit une introduction de base d'un type qui a été documenté.

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

Compilation du code

pour compiler l'exemple, 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 dans votre navigateur ou à l'aide de la commande de TYPE.

Programmation fiable

La documentation XML commence par ///. Lorsque vous créez un projet, les assistants sont des lignes de ///de départ pour vous. 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 est généré et le fichier de documentation contient 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 plus de lecture). 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 échoue, le compilateur é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 que cet élément de code. Si la vérification échoue, le compilateur é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 des 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#