Traitement du fichier XML (Guide de programmation C#)
Le compilateur génère une chaîne d'identification pour chaque construction de votre code qui est placée entre balises de manière à générer de la documentation. (Pour plus d'informations sur l'ajout de balises à votre code, consultez Balises recommandées pour commentaires de documentation.) La chaîne d'identification identifie de manière unique la construction. Les programmes qui traitent le fichier XML peuvent utiliser la chaîne d'identification pour identifier l'élément de métadonnées/réflexion du .NET Framework correspondant auquel s'applique la documentation.
Le fichier XML n'est pas une représentation hiérarchique de votre code, mais une simple liste comportant un identificateur généré pour chaque élément.
Lorsqu'il génère les chaînes d'identification, le compilateur respecte les règles suivantes :
La chaîne ne doit contenir aucun espace.
La première partie de la chaîne d'identification identifie le type de membre à l'aide d'un caractère unique suivi de deux-points. Les types de membres suivants sont utilisés :
Caractère
Description
N
Espace de noms
Vous ne pouvez pas ajouter de commentaires de documentation à un espace de noms, mais vous pouvez ajouter des références cref à ces commentaires, lorsqu'elles sont prises en charge.
T
type : classe, interface, struct, enum, délégué
F
champ
P
propriété (y compris les indexeurs ou autres propriétés indexées)
M
méthode (y compris des méthodes spéciales telles que les constructeurs, les opérateurs, etc.)
E
event
!
chaîne d'erreur
Le reste de la chaîne fournit des informations sur l'erreur. Le compilateur C# génère des informations sur l'erreur pour les liens impossibles à résoudre.
La deuxième partie de la chaîne est composée du nom complet de l'élément, à partir de la racine de l'espace de noms. Le nom de l'élément, ses types englobants et l'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 un dièse ('#'). Par principe, aucun nom d'élément ne doit contenir de signe dièse à l'origine. Par exemple, le nom complet du constructeur String est "System.String.#ctor".
Pour les propriétés et méthodes, s'il existe des arguments pour la méthode, la liste des arguments figure à la suite entre parenthèses. En l'absence d'arguments, aucune parenthèse n'est mentionnée. Les arguments sont séparés par des virgules. L'encodage de chaque argument correspond directement à son encodage dans une signature .NET Framework :
Types de base. Les types réguliers (ELEMENT_TYPE_CLASS ou ELEMENT_TYPE_VALUETYPE) sont représentés par le nom complet du type.
Types intrinsèques (par exemple, ELEMENT_TYPE_I4, ELEMENT_TYPE_OBJECT, ELEMENT_TYPE_STRING, ELEMENT_TYPE_TYPEDBYREF. et ELEMENT_TYPE_VOID) sont représentés comme le nom qualifié complet du type correspondant. Exemple : System.Int32 ou System.TypedReference.
ELEMENT_TYPE_PTR est représenté par un '*' à la suite du type modifié.
ELEMENT_TYPE_BYREF est représenté par un '@' à la suite du type modifié.
ELEMENT_TYPE_PINNED est représenté par un '^' à la suite du type modifié. Le compilateur C# ne génère jamais ceci.
ELEMENT_TYPE_CMOD_REQ est représenté par un '|' et le nom complet de la classe de modificateur, à la suite du type modifié. Le compilateur C# ne génère jamais ceci.
ELEMENT_TYPE_CMOD_OPT est représenté par un '!' et le nom complet de la classe de modificateur, à la suite du type modifié.
ELEMENT_TYPE_SZARRAY est représenté par "[]" à la suite du type d'élément du tableau.
ELEMENT_TYPE_GENERICARRAY est représenté par "[?]" à la suite du type d'élément du tableau. Le compilateur C# ne génère jamais ceci.
ELEMENT_TYPE_ARRAY est représenté par [limite_inférieure:size,limite_inférieure:size], où le nombre de virgules correspond au rang - 1, et les limite inférieure et taille de chaque dimension, lorsqu'elles sont connues, sont représentées sous forme décimale. Lorsqu'une limite inférieure ou une taille n'est pas spécifiée, elle est seulement omise. Si la limite inférieure et la taille d'une dimension particulière sont omises, le signe ':' est également omis. Par exemple, un tableau à 2 dimensions avec des limites inférieures égales à 1, mais sans tailles spécifiées est représenté par [1:,1:].
ELEMENT_TYPE_FNPTR est représenté sous la forme "=FUNC:type(signature)", où type est le type de retour et signature l'argument de la méthode. En l'absence d'arguments, les parenthèses sont omises. Le compilateur C# ne génère jamais ceci.
Les composants de signature suivants ne sont pas représentés parce qu'ils ne sont jamais utilisés pour différencier les méthodes surchargées :
convention d'appel
type de retour
ELEMENT_TYPE_SENTINEL
Uniquement pour les opérateurs de conversion (op_Implicit et op_Explicit), la valeur de retour de la méthode est encodée sous la forme d'un '~' suivi du type de retour, conformément à l'encodage effectué plus haut.
Pour les types génériques, le nom du type sera suivi du caractère ` puis d'un nombre qui indique le nombre de paramètres de type générique. Par exemple :
<member name="T:SampleClass`2"> est la balise d'un type défini comme public class SampleClass<T, U>.
Pour les méthodes qui prennent des types génériques comme paramètres, les paramètres de type générique sont spécifiés comme des nombres précédés de caractères ` (par exemple `0, `1). Chaque nombre représente une notation de tableau de base zéro pour les paramètres génériques du type.
Exemples
Les exemples ci-dessous illustrent la manière dont les chaînes d'identification doivent être générées pour une classe et ses membres :
namespace N
{
/// <summary>
/// Enter description here for class X.
/// ID string generated is "T:N.X".
/// </summary>
public unsafe class X
{
/// <summary>
/// Enter description here for the first constructor.
/// ID string generated is "M:N.X.#ctor".
/// </summary>
public X() { }
/// <summary>
/// Enter description here for the second constructor.
/// ID string generated is "M:N.X.#ctor(System.Int32)".
/// </summary>
/// <param name="i">Describe parameter.</param>
public X(int i) { }
/// <summary>
/// Enter description here for field q.
/// ID string generated is "F:N.X.q".
/// </summary>
public string q;
/// <summary>
/// Enter description for constant PI.
/// ID string generated is "F:N.X.PI".
/// </summary>
public const double PI = 3.14;
/// <summary>
/// Enter description for method f.
/// ID string generated is "M:N.X.f".
/// </summary>
/// <returns>Describe return value.</returns>
public int f() { return 1; }
/// <summary>
/// Enter description for method bb.
/// ID string generated is "M:N.X.bb(System.String,System.Int32@,System.Void*)".
/// </summary>
/// <param name="s">Describe parameter.</param>
/// <param name="y">Describe parameter.</param>
/// <param name="z">Describe parameter.</param>
/// <returns>Describe return value.</returns>
public int bb(string s, ref int y, void* z) { return 1; }
/// <summary>
/// Enter description for method gg.
/// ID string generated is "M:N.X.gg(System.Int16[],System.Int32[0:,0:])".
/// </summary>
/// <param name="array1">Describe parameter.</param>
/// <param name="array">Describe parameter.</param>
/// <returns>Describe return value.</returns>
public int gg(short[] array1, int[,] array) { return 0; }
/// <summary>
/// Enter description for operator.
/// ID string generated is "M:N.X.op_Addition(N.X,N.X)".
/// </summary>
/// <param name="x">Describe parameter.</param>
/// <param name="xx">Describe parameter.</param>
/// <returns>Describe return value.</returns>
public static X operator +(X x, X xx) { return x; }
/// <summary>
/// Enter description for property.
/// ID string generated is "P:N.X.prop".
/// </summary>
public int prop { get { return 1; } set { } }
/// <summary>
/// Enter description for event.
/// ID string generated is "E:N.X.d".
/// </summary>
public event D d;
/// <summary>
/// Enter description for property.
/// ID string generated is "P:N.X.Item(System.String)".
/// </summary>
/// <param name="s">Describe parameter.</param>
/// <returns></returns>
public int this[string s] { get { return 1; } }
/// <summary>
/// Enter description for class Nested.
/// ID string generated is "T:N.X.Nested".
/// </summary>
public class Nested { }
/// <summary>
/// Enter description for delegate.
/// ID string generated is "T:N.X.D".
/// </summary>
/// <param name="i">Describe parameter.</param>
public delegate void D(int i);
/// <summary>
/// Enter description for operator.
/// ID string generated is "M:N.X.op_Explicit(N.X)~System.Int32".
/// </summary>
/// <param name="x">Describe parameter.</param>
/// <returns>Describe return value.</returns>
public static explicit operator int(X x) { return 1; }
}
}
Voir aussi
Référence
/doc (Options du compilateur C#)
Commentaires de documentation XML (Guide de programmation C#)