Traitement des fichiers de documentation XML
Le compilateur génère une chaîne d’ID pour chaque construction de votre code qui est marquée pour générer la documentation. Pour plus d’informations, consultez les commentaires de documentation des étiquettes recommandées. La chaîne d’ID identifie de façon unique la construction. Les programmes qui traitent le fichier XML peuvent utiliser la chaîne d’ID pour identifier les métadonnées ou éléments de réflexion .NET Framework correspondants auxquels la documentation s’applique.
Le fichier XML n’est pas une représentation hiérarchique de votre code, il s’agit d’une liste plate avec un ID généré pour chaque élément.
Le compilateur respecte les règles suivantes quand 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 d’ID identifie le type du membre, avec 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, les références cref à un espace de noms sont possibles.T Type : classe, interface, struct, énumération, délégué D Typedef F Champ P Propriété (y compris les indexeurs ou d’autres propriétés indexées) M Méthode (y compris des méthodes spéciales telles que des constructeurs, des opérateurs, etc.) E Événement ! Chaîne d’erreur
Le reste de la chaîne fournit des informations sur l’erreur. Le compilateur MSVC 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 qualifié 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 l’espace de noms sont séparés par des points. Si le nom de l’élément lui-même comporte des points, ceux-ci sont remplacés par un signe dièse (« # »). Il est supposé qu’aucun élément n’a de signe dièse directement dans son nom. Par exemple, le nom complet du constructeur
StringestSystem.String.#ctor.Pour les propriétés et méthodes, si la méthode a des arguments, la liste d’arguments entre parenthèses suit. S’il n’y a pas d’arguments, aucune parenthèse n’est présente. Les arguments sont séparés par des virgules. Chaque argument est encodé de la même façon qu’il est encodé dans une signature .NET Framework :
Types de base. Les types réguliers (
ELEMENT_TYPE_CLASSouELEMENT_TYPE_VALUETYPE) sont représentés en tant que nom complet du type.Les types intrinsèques (par exemple,
ELEMENT_TYPE_I4, ,ELEMENT_TYPE_OBJECTELEMENT_TYPE_STRING,ELEMENT_TYPE_TYPEDBYREFetELEMENT_TYPE_VOID) sont représentés en tant que nom complet du type complet correspondant, par exemple,System.Int32ouSystem.TypedReference.ELEMENT_TYPE_PTRest représenté sous la forme d’un «*» suivant le type modifié.ELEMENT_TYPE_BYREFest représenté sous la forme d’un «@» suivant le type modifié.ELEMENT_TYPE_PINNEDest représenté sous la forme d’un «^» suivant le type modifié. Le compilateur MSVC ne génère jamais cet élément.ELEMENT_TYPE_CMOD_REQest représenté sous la forme d’un '|' et le nom complet de la classe modificateur, suivant le type modifié. Le compilateur MSVC ne génère jamais cet élément.ELEMENT_TYPE_CMOD_OPTest représenté sous la forme d’un '!' et le nom complet de la classe modificateur, suivant le type modifié.ELEMENT_TYPE_SZARRAYest représenté sous la forme «[]» suivant le type d’élément du tableau.ELEMENT_TYPE_GENERICARRAYest représenté sous la forme «[?]» suivant le type d’élément du tableau. Le compilateur MSVC ne génère jamais cet élément.ELEMENT_TYPE_ARRAYest représenté sous la[forme d’une taille:,de limite:inférieure inférieure,]où le nombre de virgules est le rang - 1, et la limite et la taille inférieures de chaque dimension, si elle est connue, sont représentées en décimales. Si une limite inférieure ou une taille n’est pas spécifiée, elle est omise. Si la limite inférieure et la taille sont omises pour une dimension particulière, la valeur «:» est également omise. Par exemple, un tableau à 2 dimensions avec 1 comme limite inférieure et des tailles non spécifiées est représenté en tant que[1:,1:].ELEMENT_TYPE_FNPTRest représenté par « =FUNC:type(signature) », oùtypeest le type de retour et signature correspond aux arguments de la méthode. S’il n’y a pas d’argument, les parenthèses sont omises. Le compilateur MSVC ne génère jamais cet élément.
Les composants de signature suivants ne sont pas représentés, car ils ne sont jamais utilisés pour différencier les méthodes surchargées :
Convention d'appel
Type de retour
ELEMENT_TYPE_SENTINEL
Pour les opérateurs de conversion uniquement, la valeur de retour de la méthode est encodée sous la forme d’un «
~» suivi du type de retour, comme précédemment encodé.Pour les types génériques, le nom du type est suivi d’un accent grave, puis d’un chiffre qui indique le nombre de paramètres de type générique. Par exemple :
<member name="T:MyClass`2">L’exemple montre un type défini en tant que
public class MyClass<T, U>.Pour les méthodes qui prennent des types génériques en tant que paramètres, les paramètres de type générique sont spécifiés en tant que nombres précédés avec des graduations arrière (par exemple « 0, « 1 »). Chaque nombre représente une position de tableau de base zéro pour les paramètres génériques du type.
Exemple
Les exemples suivants montrent comment les chaînes d’ID pour une classe et ses membres sont générées.
// xml_id_strings.cpp
// compile with: /clr /doc /LD
///
namespace N {
// "N:N"
/// <see cref="System" />
// <see cref="N:System"/>
ref class X {
// "T:N.X"
protected:
///
!X(){}
// "M:N.X.Finalize", destructor's representation in metadata
public:
///
X() {}
// "M:N.X.#ctor"
///
static X() {}
// "M:N.X.#cctor"
///
X(int i) {}
// "M:N.X.#ctor(System.Int32)"
///
~X() {}
// "M:N.X.Dispose", Dispose function representation in metadata
///
System::String^ q;
// "F:N.X.q"
///
double PI;
// "F:N.X.PI"
///
int f() { return 1; }
// "M:N.X.f"
///
int bb(System::String ^ s, int % y, void * z) { return 1; }
// "M:N.X.bb(System.String,System.Int32@,System.Void*)"
///
int gg(array<short> ^ array1, array< int, 2 >^ IntArray) { return 0; }
// "M:N.X.gg(System.Int16[], System.Int32[0:,0:])"
///
static X^ operator+(X^ x, X^ xx) { return x; }
// "M:N.X.op_Addition(N.X,N.X)"
///
property int prop;
// "M:N.X.prop"
///
property int prop2 {
// "P:N.X.prop2"
///
int get() { return 0; }
// M:N.X.get_prop2
///
void set(int i) {}
// M:N.X.set_prop2(System.Int32)
}
///
delegate void D(int i);
// "T:N.X.D"
///
event D ^ d;
// "E:N.X.d"
///
ref class Nested {};
// "T:N.X.Nested"
///
static explicit operator System::Int32 (X x) { return 1; }
// "M:N.X.op_Explicit(N.X!System.Runtime.CompilerServices.IsByValue)~System.Int32"
};
}
Voir aussi
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour