<summary> (guide de programmation C#)

Article
06/10/2015

<summary>description</summary>

Paramètres

description
Résumé de l'objet.

Notes

La balise <summary> doit être utilisée pour décrire un type ou un membre d'un type. Utilisez <remarks> pour ajouter des informations complémentaires à une description de type. Utilisez l'attribut cref pour activer des outils documentaires tels que Sandcastle (page éventuellement en anglais) permettant de créer des liens hypertexte internes aux pages de documentation pour les éléments de code.

Le texte de la balise <summary> est la seule source d'information sur le type dans IntelliSense. Il est également affiché dans l'Object Browser Window.

Compilez avec /doc pour traiter les commentaires de documentation et les placer dans un fichier. Pour créer la documentation finale qui est basée sur le fichier généré par le compilateur, vous pouvez créer un outil personnalisé ou utiliser un outil de type Sandcastle.

Exemple

// compile with: /doc:DocFileName.xml  

/// text for class TestClass 
public class TestClass
{
    /// <summary>DoWork is a method in the TestClass class. 
    /// <para>Here's how you could make a second paragraph in a description. <see cref="System.Console.WriteLine(System.String)"/> for information about output statements.</para>
    /// <seealso cref="TestClass.Main"/>
    /// </summary> 
    public static void DoWork(int Int1)
    {
    }

    /// text for Main 
    static void Main()
    {
    }
}

L'exemple précédent génère le fichier XML suivant.

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>YourNamespace</name>
    </assembly>
    <members>
        <member name="T:DotNetEvents.TestClass">
            text for class TestClass
        </member>
        <member name="M:DotNetEvents.TestClass.DoWork(System.Int32)">
            <summary>DoWork is a method in the TestClass class.
            <para>Here's how you could make a second paragraph in a description. <see cref="M:System.Console.WriteLine(System.String)"/> for information about output statements.</para>
            <seealso cref="M:DotNetEvents.TestClass.Main"/>
            </summary>
        </member>
        <member name="M:DotNetEvents.TestClass.Main">
            text for Main
        </member>
    </members>
</doc>

L'exemple suivant indique comment faire une référence cref à un type générique.

// compile with: /doc:DocFileName.xml  

// the following cref shows how to specify the reference, such that, 
// the compiler will resolve the reference 
/// <summary cref="C{T}">
/// </summary> 
class A { }

// the following cref shows another way to specify the reference,  
// such that, the compiler will resolve the reference 
// <summary cref="C &lt; T &gt;">

// the following cref shows how to hard-code the reference 
/// <summary cref="T:C`1">
/// </summary> 
class B { }

/// <summary cref="A">
/// </summary> 
/// <typeparam name="T"></typeparam>
class C<T> { }

L'exemple précédent génère le fichier XML suivant.

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>YourNamespace</name>
    </assembly>
    <members>
        <member name="T:ExtensionMethodsDemo1.A">
            <summary cref="T:ExtensionMethodsDemo1.C`1">
            </summary>
        </member>
        <member name="T:ExtensionMethodsDemo1.B">
            <summary cref="T:C`1">
            </summary>
        </member>
        <member name="T:ExtensionMethodsDemo1.C`1">
            <summary cref="T:ExtensionMethodsDemo1.A">
            </summary>
            <typeparam name="T"></typeparam>
        </member>
    </members>
</doc>

Voir aussi

Référence

Balises recommandées pour commentaires de documentation (Guide de programmation C#)

Concepts

Guide de programmation C#

Partager via