Commentaires de documentation annexe D

Cette annexe est informative.

D.1 Général

C# fournit un mécanisme permettant aux programmeurs de documenter leur code à l’aide d’une syntaxe de commentaire qui contient du texte XML. Dans les fichiers de code source, les commentaires ayant un certain formulaire peuvent être utilisés pour diriger un outil pour produire du code XML à partir de ces commentaires et des éléments de code source, qu’ils précèdent. Les commentaires utilisant cette syntaxe sont appelés commentaires de documentation. Ils doivent immédiatement précéder un type défini par l’utilisateur (par exemple, une classe, un délégué ou une interface) ou un membre (tel qu’un champ, un événement, une propriété ou une méthode). L’outil de génération XML est appelé générateur de documentation. (Ce générateur peut être, mais n’a pas besoin d’être, le compilateur C#lui-même.) La sortie produite par le générateur de documentation est appelée fichier de documentation. Un fichier de documentation est utilisé comme entrée dans une visionneuse de documentation ; un outil destiné à produire une sorte d’affichage visuel des informations de type et sa documentation associée.

Un compilateur C# conforme n’est pas nécessaire pour vérifier la syntaxe des commentaires de documentation ; ces commentaires sont simplement des commentaires ordinaires. Toutefois, un compilateur conforme est autorisé à effectuer cette vérification.

Cette spécification suggère un ensemble de balises standard à utiliser dans les commentaires de documentation, mais l’utilisation de ces balises n’est pas obligatoire, et d’autres balises peuvent être utilisées si vous le souhaitez, tant que les règles de xml bien formés sont suivies. Pour les implémentations C# ciblant l’interface CLI, elle fournit également des informations sur le générateur de documentation et le format du fichier de documentation. Aucune information n’est fournie sur la visionneuse de documentation.

Présentation de D.2

Les commentaires ayant un certain formulaire peuvent être utilisés pour diriger un outil pour produire du code XML à partir de ces commentaires et des éléments de code source qu’ils précèdent. Ces commentaires sont des Single_Line_Comment(§6.3.3) qui commencent par trois barres obliques (///) ou des Delimited_Comment(§6.3.3) qui commencent par une barre oblique et deux astérisques (/**). Ils doivent immédiatement précéder un type défini par l’utilisateur ou un membre qu’ils annotent. Les sections d’attribut (§22.3) sont considérées comme faisant partie des déclarations. Les commentaires de documentation doivent donc précéder les attributs appliqués à un type ou à un membre.

À des fins d’exposition, le format des commentaires de document est présenté ci-dessous sous la forme de deux règles de grammaire : Single_Line_Doc_Comment et Delimited_Doc_Comment. Toutefois, ces règles ne font pas partie de la grammaire C#, mais représentent plutôt des formats particuliers de Single_Line_Comment et Delimited_Comment règles lexer, respectivement.

Syntaxe :

Single_Line_Doc_Comment
    : '///' Input_Character*
    ;
   
Delimited_Doc_Comment
    : '/**' Delimited_Comment_Section* ASTERISK+ '/'
    ;

Dans un Single_Line_Doc_Comment, s’il existe un caractère d’espace blanc suivant les /// caractères de chacun des Single_Line_Doc_Comments adjacents au Single_Line_Doc_Comment actuel, ce caractère Whitespace n’est pas inclus dans la sortie XML.

Dans un Delimited_Doc_Comment, si le premier caractère non-Blanc sur la deuxième ligne est un ASTERISK et le même modèle de caractères blancs facultatifs et qu’un caractère ASTERISK est répété au début de chacune des lignes de l’Delimited_Doc_Comment, les caractères du modèle répété ne sont pas inclus dans la sortie XML. Le modèle peut inclure des caractères d’espace blanc après, ainsi qu’avant, le caractère ASTERISK .

Exemple :

/// <summary>
/// Class <c>Point</c> models a point in a two-dimensional plane.
/// </summary>
public class Point
{
    /// <summary>
    /// Method <c>Draw</c> renders the point.
    /// </summary>
    void Draw() {...}
}

Le texte dans les commentaires de documentation doit être bien formé en fonction des règles xml (http://www.w3.org/TR/REC-xml). Si le code XML est mal formé, un avertissement est généré et le fichier de documentation contient un commentaire indiquant qu’une erreur a été rencontrée.

Bien que les développeurs soient libres de créer leur propre ensemble de balises, un ensemble recommandé est défini dans le §D.3. Certaines des balises recommandées ont des significations spéciales :

• La balise <param> est utilisée pour décrire les paramètres. Si une telle balise est utilisée, le générateur de documentation doit vérifier que le paramètre spécifié existe et que tous les paramètres sont décrits dans les commentaires de documentation. Si cette vérification échoue, le générateur de documentation émet un avertissement.

• L’attribut cref peut être joint à n’importe quelle balise pour fournir une référence à un élément de code. Le générateur de documentation doit vérifier que cet élément de code existe. Si la vérification échoue, le générateur de documentation émet un avertissement. Lorsque vous recherchez un nom décrit dans un cref attribut, le générateur de documentation doit respecter la visibilité de l’espace de noms en fonction des instructions using apparaissant dans le code source. Pour les éléments de code génériques, la syntaxe générique normale (par exemple, «List<T> ») ne peut pas être utilisée, car elle produit du code XML non valide. Les accolades peuvent être utilisées au lieu de crochets (p. ex. «List{T} »), ou la syntaxe d’échappement XML peut être utilisée (par exemple, «List<T> »).

• La <summary> balise est destinée à être utilisée par une visionneuse de documentation pour afficher des informations supplémentaires sur un type ou un membre.

• La <include> balise inclut des informations à partir d’un fichier XML externe.

Notez soigneusement que le fichier de documentation ne fournit pas d’informations complètes sur le type et les membres (par exemple, il ne contient aucune information de type). Pour obtenir ces informations sur un type ou un membre, le fichier de documentation doit être utilisé conjointement avec la réflexion sur le type ou le membre.

Balises recommandées D.3

D.3.1 Général

Le générateur de documentation doit accepter et traiter toute balise valide en fonction des règles xml. Les balises suivantes fournissent les fonctionnalités couramment utilisées dans la documentation utilisateur. (Bien sûr, d’autres balises sont possibles.)

Graphique avec indicateur	Référence	Objectif
<c>	§D.3.2	Définir du texte dans une police de type code
<code>	§D.3.3	Définir une ou plusieurs lignes de code source ou de sortie de programme
<example>	§D.3.4	Indiquer un exemple
<exception>	§D.3.5	Identifie les exceptions qu’une méthode peut lever
<include>	§D.3.6	Inclut du code XML à partir d’un fichier externe
<list>	§D.3.7	Créer une liste ou une table
<para>	§D.3.8	Autoriser l’ajout d’une structure à du texte
<param>	§D.3.9	Décrire un paramètre pour une méthode ou un constructeur
<paramref>	§D.3.10	Identifier qu’un mot est un nom de paramètre
<permission>	§D.3.11	Documenter l’accessibilité de sécurité d’un membre
<remarks>	§D.3.12	Décrire des informations supplémentaires sur un type
<returns>	§D.3.13	Décrire la valeur de retour d’une méthode
<see>	§D.3.14	Spécifier un lien
<seealso>	§D.3.15	Générer une entrée See Also
<summary>	§D.3.16	Décrire un type ou un membre d’un type
<typeparam>	§D.3.17	Décrire un paramètre de type pour un type ou une méthode générique
<typeparamref>	§D.3.18	Identifier qu’un mot est un nom de paramètre de type
<value>	§D.3.19	Décrire une propriété

D.3.2 <c>

Cette balise fournit un mécanisme permettant d’indiquer qu’un fragment de texte dans une description doit être défini dans une police spéciale telle que celle utilisée pour un bloc de code. Pour les lignes de code réelles, utilisez <code> (§D.3.3).

Syntaxe :

<c>texte</c>

Exemple :

/// <summary>
/// Class <c>Point</c> models a point in a two-dimensional plane.
/// </summary>
public class Point
{
}

Code D.3.3 <>

Cette balise est utilisée pour définir une ou plusieurs lignes de code source ou de sortie de programme dans une police spéciale. Pour les petits fragments de code dans la narration, utilisez <c> (§D.3.2).

Syntaxe :

<code>code source ou sortie du programme</code>

Exemple :

public class Point
{
    /// <summary>
    /// This method changes the point's location by the given x- and y-offsets.
    /// <example>
    /// For example:
    /// <code>
    /// Point p = new Point(3,5);
    /// p.Translate(-1,3);
    /// </code>
    /// results in <c>p</c>'s having the value (2,8).
    /// </example>
    /// </summary>
    public void Translate(int dx, int dy)
    {
        ...
    }
}

Exemple D.3.4 <>

Cette balise permet d’utiliser un exemple de code dans un commentaire pour spécifier la façon dont une méthode ou un autre membre de bibliothèque peut être utilisé. En règle générale, cela impliquerait également l’utilisation de la balise <code> (§D.3.3) ainsi.

Syntaxe :

<example>description</example>

Exemple :

Consultez <code> (§D.3.3) pour obtenir un exemple.

Exception D.3.5 <>

Cette balise permet de documenter les exceptions qu’une méthode peut lever.

Syntaxe :

<exception cref="description du membre"></exception>

where

• cref="est" le nom d’un membre. Le générateur de documentation vérifie que le membre donné existe et traduit le membre en nom d’élément canonique dans le fichier de documentation.
• description est une description des circonstances dans lesquelles l’exception est levée.

Exemple :

class PrimaryFileFormatCorruptException : System.Exception { ... }
class PrimaryFileLockedOpenException : System.Exception { ... }

public class DataBaseOperations
{
    /// <exception cref="PrimaryFileFormatCorruptException">
    /// Thrown when the primary file is corrupted.
    /// </exception>
    /// <exception cref="PrimaryFileLockedOpenException">
    /// Thrown when the primary file is already open.
    /// </exception>
    public static void ReadRecord(int flag)
    {
        if (flag == 1)
        {
            throw new PrimaryFileFormatCorruptException();
        }
        else if (flag == 2)
        {
            throw new PrimaryFileLockedOpenException();
        }
        ...
    }
}

D.3.6 <include>

Cette balise permet d’inclure des informations à partir d’un document XML externe au fichier de code source. Le fichier externe doit être un document XML bien formé et une expression XPath est appliquée à ce document pour spécifier le code XML de ce document à inclure. La <include> balise est ensuite remplacée par le code XML sélectionné à partir du document externe.

Syntaxe :

<include file="nom de fichier" path="xpath" />

where

• file="nom" de fichier est le nom de fichier d’un fichier XML externe. Le nom de fichier est interprété par rapport au fichier qui contient la balise Include.
• path="xpath" est une expression XPath qui sélectionne certains du code XML dans le fichier XML externe.

Exemple :

Si le code source contenait une déclaration telle que :

/// <include file="docs.xml" path='extradoc/class[@name="IntList"]/*' />
public class IntList { ... }

et le fichier externe « docs.xml » contient le contenu suivant :

<?xml version="1.0"?>
<extradoc>
    <class name="IntList">
        <summary>
            Contains a list of integers.
        </summary>
    </class>
    <class name="StringList">
        <summary>
            Contains a list of strings.
        </summary>
    </class>
</extradoc>

la même documentation est alors sortie que si le code source contenait :

/// <summary>
/// Contains a list of integers.
/// </summary>
public class IntList { ... }

Liste D.3.7 <>

Cette balise est utilisée pour créer une liste ou une table d’éléments. Il peut contenir un <listheader> bloc pour définir la ligne d’en-tête d’une table ou d’une liste de définitions. (Lors de la définition d’une table, seule une entrée pour le terme dans le titre doit être fournie.)

Chaque élément de la liste est spécifié avec un bloc <item>. Lors de la création d’une liste de définitions, le terme et la description doivent être spécifiés. Toutefois, pour une table, une liste à puces ou une liste numérotée, seule la description doit être spécifiée.

Syntaxe :

<list type="bullet" | "number" | "table">
    <listheader>
        <term>term</term>
        <description>description</description>
    </listheader>
    <item>
        <term>term</term>
        <description>description</description>
    </item>
    ...
    <item>
        <term>term</term>
        <description>description</description>
    </item>
</list>

where

• terme est le terme à définir, dont la définition est en description.
• la description est un élément d’une puce ou d’une liste numérotée, ou la définition d’un terme.

Exemple :

public class MyClass
{
    /// <summary>Here is an example of a bulleted list:
    /// <list type="bullet">
    /// <item>
    /// <description>Item 1.</description>
    /// </item>
    /// <item>
    /// <description>Item 2.</description>
    /// </item>
    /// </list>
    /// </summary>
    public static void Main()
    {
        ...
    }
}

D.3.8 <para>

Cette balise est utilisée à l’intérieur d’autres balises, telles que <summary> (§D.3.16) ou <returns> (§D.3.13), et permet l’ajout de la structure au texte.

Syntaxe :

<para>content</para>

where

• le contenu est le texte du paragraphe.

Exemple :

public class Point
{
    /// <summary>This is the entry point of the Point class testing program.
    /// <para>
    /// This program tests each method and operator, and
    /// is intended to be run after any non-trivial maintenance has
    /// been performed on the Point class.
    /// </para>
    /// </summary>
    public static void Main() 
    {
        ...
    }
}

D.3.9 <param>

Cette balise est utilisée pour décrire un paramètre pour une méthode, un constructeur ou un indexeur.

Syntaxe :

<param name="nom">description</param>

where

• nom est le nom du paramètre.
• description est une description du paramètre.

Exemple :

public class Point
{
    /// <summary>
    /// This method changes the point's location to
    /// the given coordinates.
    /// </summary>
    /// <param name="xPosition">the new x-coordinate.</param>
    /// <param name="yPosition">the new y-coordinate.</param>
    public void Move(int xPosition, int yPosition)
    {
        ...
    }
}

D.3.10 <paramref>

Cette balise est utilisée pour indiquer qu’un mot est un paramètre. Le fichier de documentation peut être traité pour mettre en forme ce paramètre de manière distincte.

Syntaxe :

<paramref name="nom"/>

where

• nom est le nom du paramètre.

Exemple :

public class Point
{
    /// <summary>This constructor initializes the new Point to
    /// (<paramref name="xPosition"/>,<paramref name="yPosition"/>).
    /// </summary>
    /// <param name="xPosition">the new Point's x-coordinate.</param>
    /// <param name="yPosition">the new Point's y-coordinate.</param>
    public Point(int xPosition, int yPosition)
    {
        ...
    }
}

Autorisation D.3.11 <>

Cette balise permet de documenter l’accessibilité de sécurité d’un membre.

Syntaxe :

<permission cref="description du membre"></permission>

where

• est le nom d’un membre. Le générateur de documentation vérifie que l’élément de code donné existe et traduit le membre en nom d’élément canonique dans le fichier de documentation.
• description est une description de l’accès au membre.

Exemple :

public class MyClass
{
    /// <permission cref="System.Security.PermissionSet">
    /// Everyone can access this method.
    /// </permission>
    public static void Test()
    {
        ...
    }
}

Remarques D.3.12 <>

Cette balise est utilisée pour spécifier des informations supplémentaires sur un type. Utilisez <summary> (§D.3.16) pour décrire le type lui-même et les membres d’un type.

Syntaxe :

<remarks>description</remarks>

where

• description est le texte de la remarque.

Exemple :

/// <summary>
/// Class <c>Point</c> models a point in a two-dimensional plane.
/// </summary>
/// <remarks>
/// Uses polar coordinates
/// </remarks>
public class Point
{
    ...
}

Retours D.3.13 <>

Cette balise est utilisée pour décrire la valeur de retour d’une méthode.

Syntaxe :

<returns>description</returns>

where

• description est une description de la valeur de retour.

Exemple :

public class Point
{
    /// <summary>
    /// Report a point's location as a string.
    /// </summary>
    /// <returns>
    /// A string representing a point's location, in the form (x,y),
    /// without any leading, trailing, or embedded whitespace.
    /// </returns>
    public override string ToString() => $"({X},{Y})";
    public int X { get; set; }
    public int Y { get; set; }
}

D.3.14 <voir>

Cette balise permet à un lien d’être spécifié dans le texte. Utilisez <seealso> (§D.3.15) pour indiquer le texte à afficher dans un sous-menu Voir aussi .

Syntaxe :

<see cref="mot clé d’URLmembre" href="" langword="" />

where

• est le nom d’un membre. Le générateur de documentation vérifie que l’élément de code donné existe et change le membre du nom de l’élément dans le fichier de documentation généré.
• url est une référence à une source externe.
• langword est un mot à mettre en surbrillance d’une certaine façon.

Exemple :

public class Point
{
    /// <summary>
    /// This method changes the point's location to
    /// the given coordinates. <see cref="Translate"/>
    /// </summary>
    public void Move(int xPosition, int yPosition)
    {
        ...
    }
    /// <summary>This method changes the point's location by
    /// the given x- and y-offsets. <see cref="Move"/>
    /// </summary>
    public void Translate(int dx, int dy)
    {
        ...
    }
}

D.3.15 <seealso>

Cette balise permet de générer une entrée pour la sous-liste See Also . Utilisez <see> (§D.3.14) pour spécifier un lien à partir du texte.

Syntaxe :

<seealso cref="URL de membre" href="" />

where

• est le nom d’un membre. Le générateur de documentation vérifie que l’élément de code donné existe et change le membre du nom de l’élément dans le fichier de documentation généré.
• url est une référence à une source externe.

Exemple :

public class Point
{
    /// <summary>
    /// This method determines whether two Points have the same location.
    /// </summary>
    /// <seealso cref="operator=="/>
    /// <seealso cref="operator!="/>
    public override bool Equals(object o)
    {
        ...
    }
}

Résumé D.3.16 <>

Cette balise peut être utilisée pour décrire un type ou un membre d’un type. Utilisez <remarks> (§D.3.12) pour spécifier des informations supplémentaires sur le type ou le membre.

Syntaxe :

<summary>description</summary>

where

• description est un résumé du type ou du membre.

Exemple :

public class Point
{

    /// <summary>
    /// This constructor initializes the new Point to
    /// (<paramref name="xPosition"/>,<paramref name="yPosition"/>).
    /// </summary>
    public Point(int xPosition, int yPosition) 
    {
        ...
    }

    /// <summary>This constructor initializes the new Point to (0,0).</summary>
    public Point() : this(0, 0)
    {
    }
}

D.3.17 <typeparam>

Cette balise est utilisée pour décrire un paramètre de type pour un type ou une méthode générique.

Syntaxe :

<typeparam name="nom">description</typeparam>

where

• nom est le nom du paramètre de type.
• description est une description du paramètre de type.

Exemple :

/// <summary>A generic list class.</summary>
/// <typeparam name="T">The type stored by the list.</typeparam>
public class MyList<T>
{
   ...
}

D.3.18 <typeparamref>

Cette balise est utilisée pour indiquer qu’un mot est un paramètre de type. Le fichier de documentation peut être traité pour mettre en forme ce paramètre de type de manière distincte.

Syntaxe :

<typeparamref name="nom"/>

where

• nom est le nom du paramètre de type.

Exemple :

public class MyClass
{
    /// <summary>
    /// This method fetches data and returns a list of
    /// <typeparamref name="T"/>.
    /// </summary>
    /// <param name="query">query to execute</param>
    public List<T> FetchData<T>(string query)
    {
        ...
    }
}

Valeur D.3.19 <>

Cette balise permet à une propriété d’être décrite.

Syntaxe :

<value>description de propriété</value>

where

• la description de propriété est une description de la propriété.

Exemple :

public class Point
{
    /// <value>Property <c>X</c> represents the point's x-coordinate.</value>
    public int X { get; set; }
}

D.4 Traitement du fichier de documentation

D.4.1 Général

Les informations suivantes sont destinées aux implémentations C# ciblant l’interface CLI.

Le générateur de documentation génère une chaîne d’ID pour chaque élément du code source étiqueté avec un commentaire de documentation. Cette chaîne d’ID identifie de manière unique un élément source. Une visionneuse de documentation peut utiliser une chaîne d’ID pour identifier l’élément correspondant auquel la documentation s’applique.

Le fichier de documentation n’est pas une représentation hiérarchique du code source ; il s’agit plutôt d’une liste plate avec une chaîne d’ID générée pour chaque élément.

Format de chaîne d’ID D.4.2

Le générateur de documentation observe les règles suivantes lorsqu’il génère les chaînes d’ID :

• La chaîne ne contient aucun espace blanc.

• La première partie de la chaîne identifie le type de membre documenté, via un caractère unique suivi d’un signe deux-points. Les types de membres suivants sont définis :

  Caractère	Description
  E	Événement
  F	Champ
  M	Méthode (y compris les constructeurs, les finaliseurs et les opérateurs)
  N	Espace de noms
  P	Propriété (y compris les indexeurs)
  T	Type (par exemple, classe, délégué, énumération, interface et struct)
  !	Chaîne d’erreur ; le reste de la chaîne fournit des informations sur l’erreur. Par exemple, le générateur de documentation génère des informations d’erreur pour les liens qui ne peuvent pas être résolus.

• La deuxième partie de la chaîne est le nom complet de l’élément, en commençant à la racine de l’espace de noms. Le nom de l’élément, son ou ses types englobants et son espace de noms sont séparés par des points. Si le nom de l’élément lui-même comporte des points, ils sont remplacés par des caractères # (U+0023). (Il est supposé qu’aucun élément n’a ce caractère dans son nom.) Les arguments de type dans le nom complet, pour lequel un membre implémente explicitement un membre d’une interface générique, sont encodés en remplaçant les caractères «< » et «> » qui les entourent par les caractères «{ » et «} ».

• Pour les méthodes et les propriétés avec des arguments, la liste d’arguments suit, placée entre parenthèses. Pour ceux sans arguments, les parenthèses sont omises. Les arguments sont séparés par des virgules. L’encodage de chaque argument est identique à une signature CLI, comme suit :

  • Les arguments sont représentés par leur nom de documentation, qui est basé sur leur nom complet, modifié comme suit :
    • Les arguments qui représentent les types génériques ont un caractère «' » ajouté suivi du nombre de paramètres de type
    • Les arguments ayant le ou ref out le inmodificateur ont un @ nom de type suivant leur nom de type. Les arguments passés par valeur ou via params n’ont aucune notation spéciale.
    • Les arguments qui sont des tableaux sont représentés en tant que [ taille , entrante : inférieure ... ,lowerbound : taille ] où le nombre de virgules est le rang inférieur, et les limites et la taille inférieures de chaque dimension, si elles sont connues, sont représentées en décimales. Si une limite ou une taille inférieure n’est pas spécifiée, elle est omise. Si la limite et la taille inférieures d’une dimension particulière sont omises, le «: » est également omis. Les tableaux en javellement sont représentés par un «[] » par niveau. Les tableaux unidimensionnels omettent la limite inférieure lorsque la limite inférieure est 0 (la valeur par défaut) (§17.1).
    • Arguments qui ont des types de pointeurs autres que void ceux représentés à l’aide d’un * nom de type suivant. Un void pointeur est représenté à l’aide d’un nom de type .System.Void
    • Les arguments qui font référence aux paramètres de type générique définis sur les types sont encodés à l’aide du caractère «` » suivi de l’index de base zéro du paramètre de type.
    • Les arguments qui utilisent des paramètres de type générique définis dans les méthodes utilisent un «`` double backtick » au lieu du «` » utilisé pour les types.
    • Les arguments qui font référence aux types génériques construits sont encodés à l’aide du type générique, suivis de «{ », suivis d’une liste séparée par des virgules d’arguments de type, suivis de «} ».

Exemples de chaîne d’ID D.4.3

Les exemples suivants montrent chacun un fragment de code C#, ainsi que la chaîne d’ID produite à partir de chaque élément source capable d’avoir un commentaire de documentation :

Les types sont représentés à l’aide de leur nom complet, augmentés avec des informations génériques :

enum Color { Red, Blue, Green }

namespace Acme
{
    interface IProcess { ... }

    struct ValueType { ... }

    class Widget : IProcess
    {
        public class NestedClass { ... }
        public interface IMenuItem { ... }
        public delegate void Del(int i);
        public enum Direction { North, South, East, West }
    }

    class MyList<T>
    {
        class Helper<U,V> { ... }
    }
}

Id:

"T:Color"
"T:Acme.IProcess"
"T:Acme.ValueType"
"T:Acme.Widget"
"T:Acme.Widget.NestedClass"
"T:Acme.Widget.IMenuItem"
"T:Acme.Widget.Del"
"T:Acme.Widget.Direction"
"T:Acme.MyList`1"
"T:Acme.MyList`1.Helper`2"

Les champs sont représentés par leur nom complet.

namespace Acme
{
    struct ValueType
    {
        private int total;
    }

    class Widget : IProcess
    {
        public class NestedClass
        {
            private int value;
        }

        private string message;
        private static Color defaultColor;
        private const double PI = 3.14159;
        protected readonly double monthlyAverage;
        private long[] array1;
        private Widget[,] array2;
        private unsafe int *pCount;
        private unsafe float **ppValues;
    }
}

Id:

"F:Acme.ValueType.total"
"F:Acme.Widget.NestedClass.value"
"F:Acme.Widget.message"
"F:Acme.Widget.defaultColor"
"F:Acme.Widget.PI"
"F:Acme.Widget.monthlyAverage"
"F:Acme.Widget.array1"
"F:Acme.Widget.array2"
"F:Acme.Widget.pCount"
"F:Acme.Widget.ppValues"

Constructeurs

namespace Acme
{
    class Widget : IProcess
    {
        static Widget() { ... }
        public Widget() { ... }
        public Widget(string s) { ... }
    }
}

Id:

"M:Acme.Widget.#cctor"
"M:Acme.Widget.#ctor"
"M:Acme.Widget.#ctor(System.String)"

Finaliseurs

namespace Acme
{
    class Widget : IProcess
    {
        ~Widget() { ... }
    }
}

Id:

"M:Acme.Widget.Finalize"

Méthodes

namespace Acme
{
    struct ValueType
    {
        public void M(int i) { ... }
    }

    class Widget : IProcess
    {
        public class NestedClass
        {
            public void M(int i) { ... }
        }

        public static void M0() { ... }
        public void M1(char c, out float f, ref ValueType v, in int i) { ... }
        public void M2(short[] x1, int[,] x2, long[][] x3) { ... }
        public void M3(long[][] x3, Widget[][,,] x4) { ... }
        public unsafe void M4(char *pc, Color **pf) { ... }
        public unsafe void M5(void *pv, double *[][,] pd) { ... }
        public void M6(int i, params object[] args) { ... }
    }

    class MyList<T>
    {
        public void Test(T t) { ... }
    }

    class UseList
    {
        public void Process(MyList<int> list) { ... }
        public MyList<T> GetValues<T>(T value) { ... } 
    }
}

Id:

"M:Acme.ValueType.M(System.Int32)"
"M:Acme.Widget.NestedClass.M(System.Int32)"
"M:Acme.Widget.M0"
"M:Acme.Widget.M1(System.Char,System.Single@,Acme.ValueType@,System.Int32@)"
"M:Acme.Widget.M2(System.Int16[],System.Int32[0:,0:],System.Int64[][])"
"M:Acme.Widget.M3(System.Int64[][],Acme.Widget[0:,0:,0:][])"
"M:Acme.Widget.M4(System.Char*,Color**)"
"M:Acme.Widget.M5(System.Void*,System.Double*[0:,0:][])"
"M:Acme.Widget.M6(System.Int32,System.Object[])"
"M:Acme.MyList`1.Test(`0)"
"M:Acme.UseList.Process(Acme.MyList{System.Int32})"
"M:Acme.UseList.GetValues``1(``0)"

Propriétés et indexeurs

namespace Acme
{
    class Widget : IProcess
    {
        public int Width { get { ... } set { ... } }
        public int this[int i] { get { ... } set { ... } }
        public int this[string s, int i] { get { ... } set { ... } }
    }
}

Id:

"P:Acme.Widget.Width"
"P:Acme.Widget.Item(System.Int32)"
"P:Acme.Widget.Item(System.String,System.Int32)"

Événements

namespace Acme
{
    class Widget : IProcess
    {
        public event Del AnEvent;
    }
}

Id:

"E:Acme.Widget.AnEvent"

Opérateurs unaires

namespace Acme
{
    class Widget : IProcess
    {
        public static Widget operator+(Widget x) { ... }
    }
}

Id:

"M:Acme.Widget.op_UnaryPlus(Acme.Widget)"

L’ensemble complet de noms de fonction d’opérateur unaire utilisé est le suivant : op_UnaryPlus, , op_UnaryNegation, op_LogicalNot, op_OnesComplement, op_Increment, op_Decrement, op_True, et op_False.

Opérateurs binaires

namespace Acme
{
    class Widget : IProcess
    {
        public static Widget operator+(Widget x1, Widget x2) { ... }
    }
}

Id:

"M:Acme.Widget.op_Addition(Acme.Widget,Acme.Widget)"

L’ensemble complet de noms de fonctions d’opérateur binaire utilisés est le suivant : op_Addition, , op_Subtraction, op_Multiplyop_Division, , op_RightShiftop_LeftShiftop_Modulusop_BitwiseAndop_ExclusiveOrop_BitwiseOr, op_Equality, op_Inequalityop_LessThan, op_LessThanOrEqualop_GreaterThanet .op_GreaterThanOrEqual

Les opérateurs de conversion ont un «~ » de fin suivi du type de retour. Lorsque la source ou la destination d’un opérateur de conversion est un type générique, les caractères «< » et «"> » sont remplacés par les caractères «{ » et «} », respectivement.

namespace Acme
{
    class Widget : IProcess
    {
        public static explicit operator int(Widget x) { ... }
        public static implicit operator long(Widget x) { ... }
    }
}

Id:

"M:Acme.Widget.op_Explicit(Acme.Widget)~System.Int32"
"M:Acme.Widget.op_Implicit(Acme.Widget)~System.Int64"

D.5 Exemple

Code source D.5.1 C#

L’exemple suivant montre le code source d’une classe Point :

namespace Graphics
{
    /// <summary>
    /// Class <c>Point</c> models a point in a two-dimensional plane.
    /// </summary>
    public class Point
    {
        /// <value>
        /// Property <c>X</c> represents the point's x-coordinate.
        /// </value>
        public int X { get; set; }
        
        /// <value>
        /// Property <c>Y</c> represents the point's y-coordinate.
        /// </value>
        public int Y { get; set; }
        
        /// <summary>
        /// This constructor initializes the new Point to (0,0).
        /// </summary>
        public Point() : this(0, 0) {}
        
        /// <summary>
        /// This constructor initializes the new Point to
        /// (<paramref name="xPosition"/>,<paramref name="yPosition"/>).
        /// </summary>
        /// <param name="xPosition">The new Point's x-coordinate.</param>
        /// <param name="yPosition">The new Point's y-coordinate.</param>
        public Point(int xPosition, int yPosition) 
        {
            X = xPosition;
            Y = yPosition;
        }
        
        /// <summary>
        /// This method changes the point's location to
        /// the given coordinates. <see cref="Translate"/>
        /// </summary>
        /// <param name="xPosition">The new x-coordinate.</param>
        /// <param name="yPosition">The new y-coordinate.</param>
        public void Move(int xPosition, int yPosition) 
        {
            X = xPosition;
            Y = yPosition;
        }
        
        /// <summary>
        /// This method changes the point's location by
        /// the given x- and y-offsets.
        /// <example>For example:
        /// <code>
        /// Point p = new Point(3, 5);
        /// p.Translate(-1, 3);
        /// </code>
        /// results in <c>p</c>'s having the value (2, 8).
        /// <see cref="Move"/>
        /// </example>
        /// </summary>
        /// <param name="dx">The relative x-offset.</param>
        /// <param name="dy">The relative y-offset.</param>
        public void Translate(int dx, int dy)
        {
            X += dx;
            Y += dy;
        }
        
        /// <summary>
        /// This method determines whether two Points have the same location.
        /// </summary>
        /// <param name="o">
        /// The object to be compared to the current object.
        /// </param>
        /// <returns>
        /// True if the Points have the same location and they have
        /// the exact same type; otherwise, false.
        /// </returns>
        /// <seealso cref="operator=="/>
        /// <seealso cref="operator!="/>
        public override bool Equals(object o)
        {
            if (o == null)
            {
                return false;
            }
            if ((object)this == o) 
            {
                return true;
            }
            if (GetType() == o.GetType()) 
            {
                Point p = (Point)o;
                return (X == p.X) && (Y == p.Y);
            }
            return false;
        }

        /// <summary>
        /// This method returns a Point's hashcode.
        /// </summary>
        /// <returns>
        /// The int hashcode.
        /// </returns>
        public override int GetHashCode()
        {
            return X + (Y >> 4);    // a crude version
        }
        
        /// <summary>Report a point's location as a string.</summary>
        /// <returns>
        /// A string representing a point's location, in the form (x,y),
        /// without any leading, training, or embedded whitespace.
        /// </returns>
        public override string ToString() => $"({X},{Y})";
        
        /// <summary>
        /// This operator determines whether two Points have the same location.
        /// </summary>
        /// <param name="p1">The first Point to be compared.</param>
        /// <param name="p2">The second Point to be compared.</param>
        /// <returns>
        /// True if the Points have the same location and they have
        /// the exact same type; otherwise, false.
        /// </returns>
        /// <seealso cref="Equals"/>
        /// <seealso cref="operator!="/>
        public static bool operator==(Point p1, Point p2)
        {
            if ((object)p1 == null || (object)p2 == null)
            {
                return false;
            }
            if (p1.GetType() == p2.GetType())
            {
                return (p1.X == p2.X) && (p1.Y == p2.Y);
            }
            return false;
        }
        
        /// <summary>
        /// This operator determines whether two Points have the same location.
        /// </summary>
        /// <param name="p1">The first Point to be compared.</param>
        /// <param name="p2">The second Point to be compared.</param>
        /// <returns>
        /// True if the Points do not have the same location and the
        /// exact same type; otherwise, false.
        /// </returns>
        /// <seealso cref="Equals"/>
        /// <seealso cref="operator=="/>
        public static bool operator!=(Point p1, Point p2) => !(p1 == p2);
    }
}

D.5.2 XML résultant

Voici la sortie produite par un générateur de documentation en fonction du code source de la classe Point, illustrée ci-dessus :

<?xml version="1.0"?>
<doc>
  <assembly>
    <name>Point</name>
  </assembly>
  <members>
    <member name="T:Graphics.Point">
    <summary>Class <c>Point</c> models a point in a two-dimensional
    plane.
    </summary>
    </member>
    <member name="M:Graphics.Point.#ctor">
      <summary>This constructor initializes the new Point to (0, 0).</summary>
    </member>
    <member name="M:Graphics.Point.#ctor(System.Int32,System.Int32)">
      <summary>
        This constructor initializes the new Point to
        (<paramref name="xPosition"/>,<paramref name="yPosition"/>).
      </summary>
      <param name="xPosition">The new Point's x-coordinate.</param>
      <param name="yPosition">The new Point's y-coordinate.</param>
    </member>
    <member name="M:Graphics.Point.Move(System.Int32,System.Int32)">
      <summary>
        This method changes the point's location to
        the given coordinates.
        <see cref="M:Graphics.Point.Translate(System.Int32,System.Int32)"/>
      </summary>
      <param name="xPosition">The new x-coordinate.</param>
      <param name="yPosition">The new y-coordinate.</param>
      </member>
    <member name="M:Graphics.Point.Translate(System.Int32,System.Int32)">
      <summary>
        This method changes the point's location by
        the given x- and y-offsets.
        <example>For example:
        <code>
        Point p = new Point(3,5);
        p.Translate(-1,3);
        </code>
        results in <c>p</c>'s having the value (2,8).
        </example>
        <see cref="M:Graphics.Point.Move(System.Int32,System.Int32)"/>
      </summary>
      <param name="dx">The relative x-offset.</param>
      <param name="dy">The relative y-offset.</param>
    </member>
    <member name="M:Graphics.Point.Equals(System.Object)">
      <summary>
        This method determines whether two Points have the same location.
      </summary>
      <param name="o">
        The object to be compared to the current object.
      </param>
      <returns>
        True if the Points have the same location and they have
        the exact same type; otherwise, false.
      </returns>
      <seealso 
        cref="M:Graphics.Point.op_Equality(Graphics.Point,Graphics.Point)" />
      <seealso 
        cref="M:Graphics.Point.op_Inequality(Graphics.Point,Graphics.Point)"/>
    </member>
     <member name="M:Graphics.Point.ToString">
      <summary>
        Report a point's location as a string.
      </summary>
      <returns>
        A string representing a point's location, in the form (x,y),
        without any leading, training, or embedded whitespace.
      </returns>
     </member>
    <member name="M:Graphics.Point.op_Equality(Graphics.Point,Graphics.Point)">
      <summary>
        This operator determines whether two Points have the same location.
      </summary>
      <param name="p1">The first Point to be compared.</param>
      <param name="p2">The second Point to be compared.</param>
      <returns>
        True if the Points have the same location and they have
        the exact same type; otherwise, false.
      </returns>
      <seealso cref="M:Graphics.Point.Equals(System.Object)"/>
      <seealso
        cref="M:Graphics.Point.op_Inequality(Graphics.Point,Graphics.Point)"/>
    </member>
    <member
        name="M:Graphics.Point.op_Inequality(Graphics.Point,Graphics.Point)">
      <summary>
        This operator determines whether two Points have the same location.
      </summary>
      <param name="p1">The first Point to be compared.</param>
      <param name="p2">The second Point to be compared.</param>
      <returns>
        True if the Points do not have the same location and the
        exact same type; otherwise, false.
      </returns>
      <seealso cref="M:Graphics.Point.Equals(System.Object)"/>
      <seealso
        cref="M:Graphics.Point.op_Equality(Graphics.Point,Graphics.Point)"/>
      </member>
      <member name="M:Graphics.Point.Main">
        <summary>
          This is the entry point of the Point class testing program.
          <para>
            This program tests each method and operator, and
            is intended to be run after any non-trivial maintenance has
            been performed on the Point class.
          </para>
        </summary>
      </member>
      <member name="P:Graphics.Point.X">
        <value>
          Property <c>X</c> represents the point's x-coordinate.
        </value>
      </member>
      <member name="P:Graphics.Point.Y">
        <value>
          Property <c>Y</c> represents the point's y-coordinate.
        </value>
    </member>
  </members>
</doc>

Fin du texte informatif.