Partager via

Traitement des fichiers de documentation XML

  • Article

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 String est System.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_CLASS ou ELEMENT_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_TYPEDBYREFet ELEMENT_TYPE_VOID) sont représentés en tant que nom complet du type complet correspondant, par exemple, System.Int32 ou System.TypedReference.

    • ELEMENT_TYPE_PTR est représenté sous la forme d’un «* » suivant le type modifié.

    • ELEMENT_TYPE_BYREF est représenté sous la forme d’un «@ » suivant le type modifié.

    • ELEMENT_TYPE_PINNED est 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_REQ est 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_OPT est représenté sous la forme d’un '!' et le nom complet de la classe modificateur, suivant le type modifié.

    • ELEMENT_TYPE_SZARRAY est représenté sous la forme «[] » suivant le type d’élément du tableau.

    • ELEMENT_TYPE_GENERICARRAY est 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_FNPTR est représenté par « =FUNC:type(signature) », où type est 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 renvoyé

    • 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

Documentation XML