C# Language
Commentaires sur la documentation XML

Remarques

Annotation de méthode simple

Les commentaires sur la documentation sont placés directement au-dessus de la méthode ou de la classe qu'ils décrivent. Ils commencent par trois barres obliques /// et permettent de stocker les métadonnées via XML.

/// <summary>
/// Bar method description
/// </summary>
public void Bar()
{ 
        
}

Les informations contenues dans les balises peuvent être utilisées par Visual Studio et d’autres outils pour fournir des services tels que IntelliSense:

Voir aussi la liste de Microsoft des balises de documentation communes .

Commentaires sur la documentation de l'interface et de la classe

/// <summary>
/// This interface can do Foo
/// </summary>
public interface ICanDoFoo
{
    // ... 
}

/// <summary>
/// This Bar class implements ICanDoFoo interface
/// </summary>
public class Bar : ICanDoFoo
{
    // ...
}

Résultat

Résumé de l'interface

Résumé de classe

Commentaire sur la documentation de la méthode avec les éléments param et return

/// <summary>
/// Returns the data for the specified ID and timestamp.
/// </summary>
/// <param name="id">The ID for which to get data. </param>
/// <param name="time">The DateTime for which to get data. </param>
/// <returns>A DataClass instance with the result. </returns>
public DataClass GetData(int id, DateTime time)
{
   // ...
}

IntelliSense vous montre la description de chaque paramètre:

Conseil: Si Intellisense ne s'affiche pas dans Visual Studio, supprimez le premier crochet ou la virgule, puis tapez-le à nouveau.

Générer du code XML à partir de commentaires de documentation

Pour générer un fichier de documentation XML à partir des commentaires de documentation dans le code, utilisez l'option /doc avec le compilateur csc.exe C #.

Dans Visual Studio 2013/2015, dans Projet -> Propriétés -> Construire -> Sortie , cochez la case XML documentation file :

Lorsque vous construisez le projet, un fichier XML sera généré par le compilateur avec un nom correspondant au nom du projet (par exemple XMLDocumentation.dll -> XMLDocumentation.xml ).

Lorsque vous utilisez l'assembly dans un autre projet, assurez-vous que le fichier XML se trouve dans le même répertoire que la DLL référencée.

Cet exemple:

/// <summary>
/// Data class description
/// </summary>
public class DataClass
{
    /// <summary>
    /// Name property description
    /// </summary>
    public string Name { get; set; }
}


/// <summary>
/// Foo function
/// </summary>
public class Foo
{
    /// <summary>
    /// This method returning some data
    /// </summary>
    /// <param name="id">Id parameter</param>
    /// <param name="time">Time parameter</param>
    /// <returns>Data will be returned</returns>
    public DataClass GetData(int id, DateTime time)
    {
        return new DataClass();
    }
}

Produit ce xml sur build:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>XMLDocumentation</name>
    </assembly>
    <members>
        <member name="T:XMLDocumentation.DataClass">
            <summary>
            Data class description
            </summary>
        </member>
        <member name="P:XMLDocumentation.DataClass.Name">
            <summary>
            Name property description
            </summary>
        </member>
        <member name="T:XMLDocumentation.Foo">
            <summary>
            Foo function
            </summary>
        </member>
        <member name="M:XMLDocumentation.Foo.GetData(System.Int32,System.DateTime)">
            <summary>
            This method returning some data
            </summary>
            <param name="id">Id parameter</param>
            <param name="time">Time parameter</param>
            <returns>Data will be returned</returns>
        </member>
    </members>
</doc>

Référencement d'une autre classe dans la documentation

La <see> peut être utilisée pour créer un lien vers une autre classe. Il contient le membre cref qui doit contenir le nom de la classe à référencer. Visual Studio fournira Intellsense lors de l'écriture de cette balise et ces références seront traitées lors du renommage de la classe référencée.

/// <summary>
/// You might also want to check out <see cref="SomeOtherClass"/>.
/// </summary>
public class SomeClass
{
}

Dans les fenêtres contextuelles de Visual Studio Intellisense, ces références seront également affichées en couleur dans le texte.

Pour référencer une classe générique, utilisez quelque chose de similaire à ce qui suit:

/// <summary>
/// An enhanced version of <see cref="List{T}"/>.
/// </summary>
public class SomeGenericClass<T>
{
}