Verarbeiten der XML-Datei (C# Programmierhandbuch)
Für jedes Konstrukt, das zum Generieren von Dokumentation gekennzeichnet ist, wird vom Compiler eine ID-Zeichenfolge generiert.(Weitere Informationen darüber, wie Code mit Tags versehen werden kann, finden Sie unter Empfohlene Tags für Dokumentationskommentare.) Das Konstrukt wird von der ID-Zeichenfolge eindeutig identifiziert.Programme, von denen die XML-Datei verarbeitet wird, können die ID-Zeichenfolge einsetzen, um das entsprechende .NET Framework-Metadaten-/Reflektionselement zu identifizieren, auf das die Dokumentation angewendet werden kann.
Die XML-Datei enthält keine hierarchische Darstellung des Codes. Es handelt sich um eine unstrukturierte Liste mit einer generierten ID für jedes Element.
Die folgenden Regeln werden vom Compiler beim Generieren der ID-Zeichenfolgen beachtet:
Die Zeichenfolge darf keinen Leerraum enthalten.
Der erste Teil der ID-Zeichenfolge kennzeichnet die Art des zu identifizierenden Members durch ein einzelnes Zeichen, gefolgt von einem Doppelpunkt.Die folgenden Membertypen werden verwendet:
Zeichen
Beschreibung
N
-Namespace
Einem Namespace können keine Dokumentationskommentare hinzugefügt werden. Falls unterstützt, können jedoch cref-Verweise hinzugefügt werden.
T
Typ: Klasse, Schnittstelle, Struktur, Auflistung, Delegat
F
Feld
P
Eigenschaft, einschließlich Indexern oder anderer indizierter Eigenschaften.
M
Methode (einschließlich spezieller Methoden wie Konstruktoren, Operatoren usw.)
E
event
!
Fehlerzeichenfolge
Der verbleibende Teil der Zeichenfolge enthält Fehlerinformationen.Vom C#-Compiler werden Fehlerinformationen für Links, die nicht aufgelöst werden können, erstellt.
Beim zweiten Teil der Zeichenfolge handelt es sich um den vollqualifizierten Namen eines Elements, beginnend mit dem Namespace-Stammverzeichnis.Der Name des Elements, der bzw. die einschließende(n) Typ(en) und der Namespace sind durch Punkte getrennt.Wenn der Name des Elements selbst Punkte enthält, werden sie durch ein Nummernzeichen (#) ersetzt.Es wird vorausgesetzt, dass kein Element direkt im Namen ein Nummernzeichen enthält.Der vollqualifizierte Name des String-Konstruktors würde beispielsweise "System.String.#ctor" lauten.
Wenn es sich bei Eigenschaften und Methoden um Argumente der Methode handelt, folgt die in Klammern eingeschlossene Argumentliste.Wenn keine Argumente vorhanden sind, werden keine Klammern verwendet.Die Argumente werden durch Kommas voneinander getrennt.Die Codierung jedes Arguments erfolgt genauso wie die Codierung in einer .NET Framework-Signatur:
Basistypen.Reguläre Typen, ELEMENT_TYPE_CLASS oder ELEMENT_TYPE_VALUETYPE, werden als vollqualifizierter Name des Typs repräsentiert.
Systeminterne Typen, z. B. ELEMENT_TYPE_I4, ELEMENT_TYPE_OBJECT, ELEMENT_TYPE_STRING, ELEMENT_TYPE_TYPEDBYREF.und ELEMENT_TYPE_VOID) werden als vollqualifizierter Name des entsprechenden vollständigen Typs repräsentiert.Als Beispiel sei hier System.Int32 oder System.TypedReference aufgeführt.
ELEMENT_TYPE_PTR wird als *, das auf den geänderten Typ folgt, repräsentiert.
ELEMENT_TYPE_PTR wird als @, das auf den geänderten Typ folgt, repräsentiert.
ELEMENT_TYPE_PTR wird als ^, das auf den geänderten Typ folgt, repräsentiert.Dies wird nie vom C#-Compiler generiert.
ELEMENT_TYPE_CMOD_REQ wird als '|' mit nachstehendem vollqualifizierten Namen der Modifiziererklasse repräsentiert, das auf den geänderten Typ folgt.Dies wird nie vom C#-Compiler generiert.
ELEMENT_TYPE_CMOD_OPT wird als '!' mit nachstehendem vollqualifizierten Namen der Modifiziererklasse repräsentiert, das auf den geänderten Typ folgt.
ELEMENT_TYPE_SZARRAY wird als [], das auf den Elementtyp des Arrays folgt, repräsentiert.
ELEMENT_TYPE_GENERICARRAY wird als [?], das auf den Elementtyp des Arrays folgt, repräsentiert.Dies wird nie vom C#-Compiler generiert.
ELEMENT_TYPE_ARRAY wird als [lowerbound:size,lowerbound:size] repräsentiert, wobei die Anzahl der Kommas durch Rang - 1 berechnet wird und die untere Grenze sowie die Größe jeder Dimension, sofern bekannt, dezimal repräsentiert werden.Wenn die untere Grenze oder die Größe nicht angegeben ist, wird sie einfach ausgelassen.Wenn die untere Grenze und die Größe für eine bestimmte Dimension ausgelassen werden, kann der : ebenfalls ausgelassen werden.[1:,1:] ist beispielsweise ein zweidimensionales Array mit 1 als unterer Grenze und nicht angegebenen Größen.
ELEMENT_TYPE_FNPTR wird als "=FUNC:type(signature)" repräsentiert, wobei type den Rückgabetyp darstellt und es sich bei signature um die Argumente der Methode handelt.Sind keine Argumente vorhanden, werden keine Klammern verwendet.Dies wird nie vom C#-Compiler generiert.
Die folgenden Signaturkomponenten werden nicht repräsentiert, weil sie nicht zur Unterscheidung überladener Methoden verwendet werden:
Aufrufkonvention
Rückgabetyp
ELEMENT_TYPE_SENTINEL
Nur für Konvertierungsoperatoren, op_Implicit und op_Explicit, wird der Rückgabewert der Methode als "~" gefolgt vom Rückgabewert codiert, wie weiter oben gezeigt.
Bei generischen Typen folgt auf den Namen des Typs ein Graviszeichen und dann eine Zahl, die die Anzahl der generischen Typparameter angibt.Beispiel:
<member name="T:SampleClass`2"> ist das Tag für einen Typ, der als public class SampleClass<T, U> definiert wird.
Bei Methoden, die generische Typen als Parameter verwenden, werden die generischen Parameter des Typs als Zahlen mit vorangestelltem Graviszeichen angegeben (z. B. `0,`1).Jede Zahl stellt eine bei 0 beginnende Arraynotation für die generischen Parameter des Typs dar.
Beispiele
In den folgenden Beispielen wird eine mögliche Generierung von ID-Zeichenfolgen für eine Klasse und ihre Member gezeigt:
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; }
}
}
Siehe auch
Referenz
XML-Dokumentationskommentare (C#-Programmierhandbuch)