Freigeben über

Generieren von XML-API-Dokumentationskommentaren

C#-Quelldateien können strukturierte Kommentare enthalten, die API-Dokumentationen für die in diesen Dateien definierten Typen erzeugen. Der C#-Compiler erzeugt eine XML-Datei , die strukturierte Daten enthält, die Kommentare und API-Signaturen darstellen. Andere Tools können diese XML-Ausgabe verarbeiten, um beispielsweise lesbare Dokumentationen in Form von Webseiten oder PDF-Dateien zu erstellen.

Dieser Prozess bietet ihnen viele Vorteile, um die API-Dokumentation in Ihrem Code hinzuzufügen:

  • Der C#-Compiler kombiniert die Struktur des C#-Codes mit dem Text der Kommentare in einem einzelnen XML-Dokument.
  • Der C#-Compiler überprüft, ob die Kommentare den API-Signaturen für relevante Tags entsprechen.
  • Tools, die die XML-Dokumentationsdateien verarbeiten, können XML-Elemente und Attribute definieren, die für diese Tools spezifisch sind.

Tools wie Visual Studio bieten IntelliSense für viele gängige XML-Elemente, die in Dokumentationskommentaren verwendet werden.

In diesem Artikel werden die folgenden Themen behandelt:

  • Dokumentationskommentare und XML-Dateigenerierung
  • Vom C#-Compiler und Visual Studio überprüfte Tags
  • Format der generierten XML-Datei

Xml-Dokumentationsausgabe erstellen

Sie erstellen eine Dokumentation für Ihren Code, indem Sie spezielle Kommentarfelder schreiben, die durch dreifache Schrägstriche gekennzeichnet sind. Die Kommentarfelder enthalten XML-Elemente, die den Codeblock beschreiben, der den Kommentaren folgt. Beispiel:

/// <summary>
/// This class performs an important function.
/// </summary>
public class MyClass { }

Sie legen entweder die Option GenerateDocumentationFile oder DocumentationFile fest, und der Compiler findet alle Kommentarfelder mit XML-Tags im Quellcode und erstellt eine XML-Dokumentationsdatei aus diesen Kommentaren. Wenn diese Option aktiviert ist, generiert der Compiler die CS1591-Warnung für alle öffentlich sichtbaren Member, die in Ihrem Projekt ohne XML-Dokumentationskommentare deklariert wurden.

XML-Kommentarformate

Die Verwendung von XML-Dokumentkommentaren erfordert Trennzeichen, die angeben, wo ein Dokumentationskommentar beginnt und endet. Sie verwenden die folgenden Trennzeichen mit den XML-Dokumentationstags:

  • /// Einzeiliges Trennzeichen: Die Dokumentationsbeispiele und C#-Projektvorlagen verwenden dieses Formular. Wenn Leerzeichen auf das Trennzeichen folgt, ist sie nicht in der XML-Ausgabe enthalten.

    Hinweis

    Visual Studio fügt den <summary> Cursor automatisch ein und </summary> positioniert den Cursor innerhalb dieser Tags, nachdem Sie das /// Trennzeichen im Code-Editor eingegeben haben. Sie können dieses Feature im Dialogfeld "Optionen" aktivieren oder deaktivieren.

  • /** */ Mehrzeilentrennzeichen: Die /** */ Trennzeichen weisen die folgenden Formatierungsregeln auf:

    • Wenn die restliche Zeile leer ist, wird die Zeile in der Zeile, die das Trennzeichen enthält /** , nicht für Kommentare verarbeitet. Wenn das erste Zeichen nach dem /** Trennzeichen Leerzeichen ist, wird dieses Leerzeichen ignoriert, und der Rest der Zeile wird verarbeitet. Andernfalls wird der gesamte Text der Zeile nach dem /** Trennzeichen als Teil des Kommentars verarbeitet.

    • Wenn in der Zeile, die das */ Trennzeichen enthält, nur Leerzeichen bis zum */ Trennzeichen vorhanden sind, wird diese Zeile ignoriert. Andernfalls wird der Text in der Zeile bis zum */ Trennzeichen als Teil des Kommentars verarbeitet.

    • Für die Zeilen nach der Zeile, die mit dem /** Trennzeichen beginnt, sucht der Compiler am Anfang jeder Zeile nach einem gemeinsamen Muster. Das Muster kann aus optionalem Leerzeichen und/oder einem Sternchen (*) bestehen, gefolgt von optionalem Leerraum. Wenn der Compiler am Anfang jeder Zeile ein allgemeines Muster findet, das nicht mit dem /** Trennzeichen beginnt oder mit dem */ Trennzeichen endet, wird dieses Muster für jede Zeile ignoriert.

    • Der einzige Teil des folgenden Kommentars ist die Zeile, mit der begonnen wird <summary>. Die drei Tagformate erzeugen dieselben Kommentare.

      /** <summary>text</summary> */

/**
<summary>text</summary>
*/

/**
* <summary>text</summary>
*/

    • Der Compiler identifiziert ein gemeinsames Muster von " * " am Anfang der zweiten und dritten Zeile. Das Muster ist nicht in der Ausgabe enthalten.

      /**
* <summary>
* text </summary>*/

    • Der Compiler findet kein gängiges Muster im folgenden Kommentar, da das zweite Zeichen in der dritten Zeile kein Sternchen ist. Der gesamte Text in der zweiten und dritten Zeile wird als Teil des Kommentars verarbeitet.

      /**
* <summary>
   text </summary>
*/

    • Der Compiler findet aus zwei Gründen kein Muster im folgenden Kommentar. Erstens ist die Anzahl der Leerzeichen vor dem Sternchen nicht konsistent. Zweitens beginnt die fünfte Zeile mit einer Registerkarte, die nicht mit Leerzeichen übereinstimmt. Der gesamte Text aus den Zeilen 2 bis fünf wird als Teil des Kommentars verarbeitet.

      /**
  * <summary>
  * text
*  text2
 	*  </summary>
*/

Um auf XML-Elemente zu verweisen (z. B. verarbeitet Ihre Funktion bestimmte XML-Elemente, die Sie in einem XML-Dokumentationskommentar beschreiben möchten), können Sie den standardmäßigen Quotingmechanismus (&lt; und &gt;) verwenden. Um auf generische Bezeichner in Codeverweiselementen (cref) zu verweisen, können Sie entweder die Escapezeichen (z cref="List&lt;T&gt;". B. ) oder geschweifte Klammern (cref="List{T}") verwenden. Als Sonderfall analysiert der Compiler die geschweiften Klammern als eckige Klammern, um den Dokumentationskommentar beim Verweisen auf generische Bezeichner weniger umständlich für den Autor zu machen.

Hinweis

Wenn Sie Kommentare mithilfe des Einzeiligen-XML-Kommentartrennzeichens schreiben, ///aber keine Tags enthalten, fügt der Compiler der XML-Ausgabedatei den Text dieser Kommentare hinzu. Die Ausgabe enthält jedoch keine XML-Elemente wie <summary>z. B. . Die meisten Tools, die XML-Kommentare nutzen (einschließlich Visual Studio IntelliSense), lesen diese Kommentare nicht.

Tools, die XML-Dokumentationseingaben akzeptieren

Die folgenden Tools erstellen eine Ausgabe aus XML-Kommentaren:

  • DocFX: DocFX ist ein API-Dokumentationsgenerator für .NET, der derzeit C#, Visual Basic und F# unterstützt. Außerdem können Sie die generierte Referenzdokumentation anpassen. DocFX erstellt eine statische HTML-Website aus Ihrem Quellcode und Markdown-Dateien. DocFX bietet Ihnen außerdem die Flexibilität, das Layout und den Stil Ihrer Website über Vorlagen anzupassen. Sie können auch benutzerdefinierte Vorlagen erstellen.
  • Sandcastle: Die Sandcastle-Tools erstellen Hilfedateien für verwaltete Klassenbibliotheken, die sowohl konzeptionelle als auch API-Referenzseiten enthalten. Die Sandcastle-Tools sind befehlszeilenbasiert und verfügen nicht über GUI-Front-End-, Projektverwaltungsfeatures oder automatisierten Buildprozess. Der Sandcastle-Hilfedatei-Generator bietet eigenständige GUI- und Befehlszeilentools, um eine Hilfedatei automatisch zu erstellen. Ein Visual Studio-Integrationspaket ist auch dafür verfügbar, sodass Hilfeprojekte vollständig in Visual Studio erstellt und verwaltet werden können.
  • Doxygen: Doxygen generiert einen Onlinedokumentationsbrowser (in HTML) oder ein Offlinereferenzhandbuch (in LaTeX) aus einer Reihe dokumentierter Quelldateien. Es gibt auch Unterstützung für das Generieren der Ausgabe in RTF (MS Word), PostScript, hyperlinked PDF, komprimierter HTML- und DocBook- und Unix-Manuellen Seiten. Sie können Doxygen so konfigurieren, dass die Codestruktur aus nicht dokumentierten Quelldateien extrahiert wird.

Hinweis

Die XML-Dokumentationskommentare sind keine Metadaten; sie sind nicht in der kompilierten Assembly enthalten und sind daher nicht durch Spiegelung zugänglich.

ID-Zeichenfolgen

Jeder Typ oder Member wird in einem Element in der XML-Ausgabedatei gespeichert. Jedes dieser Elemente weist eine eindeutige ID-Zeichenfolge auf, die den Typ oder das Element identifiziert. Die ID-Zeichenfolge muss Operatoren, Parametern, Rückgabewerten, generischen Typparametern, ref, inund out Parametern entsprechen. Um alle diese potenziellen Elemente zu codieren, folgt der Compiler klar definierten Regeln zum Generieren der ID-Zeichenfolgen. Programme, die die XML-Datei verarbeiten, verwenden die ID-Zeichenfolge, um die entsprechenden .NET-Metadaten oder Spiegelungselemente zu identifizieren, für die die Dokumentation gilt.

Der Compiler beachtet die folgenden Regeln, wenn er die ID-Zeichenfolgen generiert:

  • In der Zeichenfolge befindet sich kein Leerzeichen.

  • Der erste Teil der Zeichenfolge identifiziert die Art des Elements mithilfe eines einzelnen Zeichens gefolgt von einem Doppelpunkt. Die folgenden Membertypen werden verwendet:

    Charakter Memberart Hinweise
    N Namespace Sie können einem Namespace keine Dokumentationskommentare hinzufügen, aber Sie können verweise darauf erstellen cref , wo diese unterstützt werden.
    T Typ Ein Typ ist eine Klasse, Schnittstelle, Struktur, Enumeration oder Stellvertretung.
    F Feld
    P Eigentum Enthält Indexer oder andere indizierte Eigenschaften.
    M Methode Enthält spezielle Methoden wie Konstruktoren und Operatoren.
    E Ereignis
    ! Fehlerzeichenfolge Der Rest der Zeichenfolge enthält Informationen zum Fehler. Der C#-Compiler generiert Fehlerinformationen für Verknüpfungen, die nicht behoben werden können.

  • Der zweite Teil der Zeichenfolge ist der vollqualifizierte Name des Elements, beginnend mit dem Stamm des Namespaces. Der Name des Elements, seine eingeschlossenen Typen und Namespaces werden durch Punkte getrennt. Wenn der Name des Elements selbst Punkte enthält, werden sie durch das Hashzeichen ('#') ersetzt. Bei der Grammatik wird davon ausgegangen, dass kein Element über ein Hashzeichen direkt in seinem Namen verfügt. Der vollqualifizierte Name des Zeichenfolgenkonstruktors lautet z. B. "System.String.#ctor".

  • Für Eigenschaften und Methoden folgt die in Klammern eingeschlossene Parameterliste. Wenn keine Parameter vorhanden sind, sind keine Klammern vorhanden. Die Parameter werden durch Kommas getrennt. Die Codierung der einzelnen Parameter folgt direkt, wie er in einer .NET-Signatur codiert wird (Siehe Microsoft.VisualStudio.CorDebugInterop.CorElementType Definitionen aller Caps-Elemente in der folgenden Liste):

    • Basistypen. Reguläre Typen (ELEMENT_TYPE_CLASS oder ELEMENT_TYPE_VALUETYPE) werden als vollqualifizierter Name des Typs dargestellt.
    • Systeminterne Typen (z ELEMENT_TYPE_I4. B. , , ELEMENT_TYPE_OBJECT, ELEMENT_TYPE_STRING, ELEMENT_TYPE_TYPEDBYREFund ELEMENT_TYPE_VOID) werden als vollqualifizierter Name des entsprechenden vollständigen Typs dargestellt. Zum Beispiel: System.Int32 oder System.TypedReference.
    • ELEMENT_TYPE_PTR wird als '*' nach dem geänderten Typ dargestellt.
    • ELEMENT_TYPE_BYREF wird als '@' nach dem geänderten Typ dargestellt.
    • ELEMENT_TYPE_CMOD_OPT wird als '!' und der vollqualifizierte Name der Modifiziererklasse nach dem geänderten Typ dargestellt.
    • ELEMENT_TYPE_SZARRAY wird als "[]" nach dem Elementtyp des Arrays dargestellt.
    • ELEMENT_TYPE_ARRAY wird als [untere Grenze:size,untere Grenze:size] dargestellt, wobei die Anzahl der Kommas der Rang - 1 ist, und die untere Grenze und Größe der einzelnen Dimensionen( falls bekannt) im Dezimaltrennzeichen dargestellt werden. Die untere Grenze und Größe werden weggelassen, wenn sie nicht angegeben sind. Wenn die untere Grenze und Größe für eine bestimmte Dimension nicht angegeben wird, wird auch das ':' weggelassen. Ein zweidimensionales Array mit 1 als untere Grenzen und nicht angegebene Größen lautet z. B. [1:,1:].

  • Nur für Konvertierungsoperatoren (op_Implicit und op_Explicit) wird der Rückgabewert der Methode als ~ gefolgt vom Rückgabetyp codiert. Beispiel: <member name="M:System.Decimal.op_Explicit(System.Decimal arg)~System.Int32"> ist das Tag für den in der System.Decimal Klasse deklarierten Umwandlungsoperatorpublic static explicit operator int (decimal value);.

  • Bei generischen Typen folgt auf den Namen des Typs ein Backtick 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 ist. Bei Methoden, die generische Typen als Parameter verwenden, werden die generischen Typparameter als Zahlen angegeben, die mit Backticks (z. B. "0,"1) vorangestellt sind. Jede Zahl stellt eine nullbasierte Arraynotation für die generischen Parameter des Typs dar.

    • ELEMENT_TYPE_PINNED wird als '^' nach dem geänderten Typ dargestellt. Der C#-Compiler generiert diese Codierung nie.
    • ELEMENT_TYPE_CMOD_REQ wird als '|' und der vollqualifizierte Name der Modifiziererklasse nach dem geänderten Typ dargestellt. Der C#-Compiler generiert diese Codierung nie.
    • ELEMENT_TYPE_GENERICARRAY wird als "[?]" nach dem Elementtyp des Arrays dargestellt. Der C#-Compiler generiert diese Codierung nie.
    • ELEMENT_TYPE_FNPTR wird als "=FUNC:type(signature)" dargestellt. type Dabei handelt es sich um den Rückgabetyp, und die Signatur ist die Argumente der Methode. Wenn keine Argumente vorhanden sind, werden die Klammern weggelassen. Der C#-Compiler generiert diese Codierung nie.
    • Die folgenden Signaturkomponenten werden nicht dargestellt, da sie nicht zum Unterscheiden überladener Methoden verwendet werden:
      • Aufrufkonvention
      • Rückgabetyp
      • ELEMENT_TYPE_SENTINEL

Die folgenden Beispiele zeigen, wie die ID-Zeichenfolgen für eine Klasse und deren Member generiert werden:

namespace MyNamespace;

/// <summary>
/// Enter description here for class X.
/// ID string generated is "T:MyNamespace.MyClass".
/// </summary>
public unsafe class MyClass
{
    /// <summary>
    /// Enter description here for the first constructor.
    /// ID string generated is "M:MyNamespace.MyClass.#ctor".
    /// </summary>
    public MyClass() { }

    /// <summary>
    /// Enter description here for the second constructor.
    /// ID string generated is "M:MyNamespace.MyClass.#ctor(System.Int32)".
    /// </summary>
    /// <param name="i">Describe parameter.</param>
    public MyClass(int i) { }

    /// <summary>
    /// Enter description here for field Message.
    /// ID string generated is "F:MyNamespace.MyClass.Message".
    /// </summary>
    public string? Message;

    /// <summary>
    /// Enter description for constant PI.
    /// ID string generated is "F:MyNamespace.MyClass.PI".
    /// </summary>
    public const double PI = 3.14;

    /// <summary>
    /// Enter description for method Func.
    /// ID string generated is "M:MyNamespace.MyClass.Func".
    /// </summary>
    /// <returns>Describe return value.</returns>
    public int Func() => 1;

    /// <summary>
    /// Enter description for method SomeMethod.
    /// ID string generated is "M:MyNamespace.MyClass.SomeMethod(System.String,System.Int32@,System.Void*)".
    /// </summary>
    /// <param name="str">Describe parameter.</param>
    /// <param name="num">Describe parameter.</param>
    /// <param name="ptr">Describe parameter.</param>
    /// <returns>Describe return value.</returns>
    public int SomeMethod(string str, ref int num, void* ptr) { return 1; }

    /// <summary>
    /// Enter description for method AnotherMethod.
    /// ID string generated is "M:MyNamespace.MyClass.AnotherMethod(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 AnotherMethod(short[] array1, int[,] array) { return 0; }

    /// <summary>
    /// Enter description for operator.
    /// ID string generated is "M:MyNamespace.MyClass.op_Addition(MyNamespace.MyClass,MyNamespace.MyClass)".
    /// </summary>
    /// <param name="first">Describe parameter.</param>
    /// <param name="second">Describe parameter.</param>
    /// <returns>Describe return value.</returns>
    public static MyClass operator +(MyClass first, MyClass second) { return first; }

    /// <summary>
    /// Enter description for property.
    /// ID string generated is "P:MyNamespace.MyClass.Prop".
    /// </summary>
    public int Prop { get { return 1; } set { } }

    /// <summary>
    /// Enter description for event.
    /// ID string generated is "E:MyNamespace.MyClass.OnHappened".
    /// </summary>
    public event Del? OnHappened;

    /// <summary>
    /// Enter description for index.
    /// ID string generated is "P:MyNamespace.MyClass.Item(System.String)".
    /// </summary>
    /// <param name="str">Describe parameter.</param>
    /// <returns></returns>
    public int this[string s] => 1;

    /// <summary>
    /// Enter description for class Nested.
    /// ID string generated is "T:MyNamespace.MyClass.Nested".
    /// </summary>
    public class Nested { }

    /// <summary>
    /// Enter description for delegate.
    /// ID string generated is "T:MyNamespace.MyClass.Del".
    /// </summary>
    /// <param name="i">Describe parameter.</param>
    public delegate void Del(int i);

    /// <summary>
    /// Enter description for operator.
    /// ID string generated is "M:MyNamespace.MyClass.op_Explicit(MyNamespace.MyClass)~System.Int32".
    /// </summary>
    /// <param name="myParameter">Describe parameter.</param>
    /// <returns>Describe return value.</returns>
    public static explicit operator int(MyClass myParameter) => 1;
}

C#-Sprachspezifikation

Weitere Informationen finden Sie im Anhang zur C#-Sprachspezifikation zu Dokumentationskommentaren.

  • Last updated on