Freigeben über

Empfohlene XML-Tags für C#-Dokumentationskommentare

C#-Dokumentationskommentare verwenden XML-Elemente, um die Struktur der Ausgabedokumentation zu definieren. Eine Folge dieses Features ist, dass Sie in Ihren Dokumentationskommentaren beliebige gültige XML-Elemente hinzufügen können. Der C#-Compiler kopiert diese Elemente in die XML-Ausgabedatei. Sie können zwar beliebige gültige XML-Elemente in Ihren Kommentaren verwenden (einschließlich aller gültigen HTML-Elemente), Codedokumentierung wird jedoch aus vielen Gründen empfohlen.

Nachstehend finden Sie einige Empfehlungen, allgemeine Anwendungsfallszenarios und wissenswerte Hinweise für den Fall, dass Sie XML-Dokumentationstags in Ihrem C#-Code verwenden. Sie können zwar beliebige Tags in Ihren Dokumentationskommentaren verwenden, in diesem Artikel werden jedoch die empfohlenen Tags für die gängigsten Sprachkonstrukte beschrieben. Sie sollten immer die folgenden Empfehlungen befolgen:

  • Aus Einheitlichkeitsgründen sollten alle öffentlich sichtbaren Typen und deren öffentliche Member dokumentiert werden.
  • Private Member können auch mithilfe von XML-Kommentaren dokumentiert werden. Dies legt jedoch die interne (potenziell vertrauliche) Funktionsweise Ihrer Bibliothek offen.
  • Als absolutes Minimum sollten Typen und deren Member über ein <summary>-Tag verfügen.
  • Dokumentationstext sollte in vollständigen Sätze geschrieben werden, die mit Punkten enden.
  • Partielle Klassen werden vollständig unterstützt, und Dokumentationsinformationen werden für jeden Typ zu einem einzelnen Eintrag verkettet. Wenn beide Deklarationen eines Teilmitglieds Dokumentationskommentare haben, werden die Kommentare zur Implementierungsdeklaration in das Ausgabe-XML geschrieben.

Die XML-Dokumentation beginnt mit ///. Wenn Sie ein neues Projekt erstellen, fügen die Vorlagen einige ///-Startzeilen für Sie ein. Die Verarbeitung dieser Kommentare weist einige Einschränkungen auf:

  • Die Dokumentation muss wohlgeformtes XML sein. Wenn der XML-Code nicht wohlgeformt ist, generiert der Compiler eine Warnung. Die Dokumentationsdatei enthält einen Kommentar, der besagt, dass ein Fehler aufgetreten ist.
  • Einige der empfohlenen Tags haben eine besondere Bedeutung:
    • Das <param>-Tag wird verwendet, um Parameter zu beschreiben. Wenn es verwendet wird, überprüft der Compiler, ob der Parameter vorhanden ist, und ob alle Parameter in der Dokumentation beschrieben werden. Wenn die Überprüfung fehlschlägt, gibt der Compiler eine Warnung aus.
    • Das cref-Attribut kann an jedes Tag angefügt werden, um auf ein Codeelement zu verweisen. Der Compiler überprüft, ob dieses Codeelement vorhanden ist. Wenn die Überprüfung fehlschlägt, gibt der Compiler eine Warnung aus. Der Compiler berücksichtigt alle using-Direktiven, wenn er nach einem Typ sucht, der im cref-Attribut beschrieben wird.
    • Das <summary>-Tag wird von IntelliSense in Visual Studio verwendet, um zusätzliche Informationen über einen Typ oder Member anzuzeigen.

      Hinweis

      Die XML-Datei enthält keine vollständigen Informationen über den Typ und die Member (z. B. fehlen Typinformationen). Verwenden Sie die Dokumentationsdatei zusammen mit Reflektion über den tatsächlichen Typ oder Member, um vollständige Informationen zu einem Typ oder Member zu erhalten.

  • Entwickler können ihren eigenen Satz von Tags erstellen. Der Compiler kopiert diese Tags in die Ausgabedatei.

Einige der empfohlenen Tags können für jedes Sprachelement verwendet werden. Andere haben speziellere Anwendungsfälle. Wieder andere Tags werden eingesetzt, um Text in Ihrer Dokumentation zu formatieren. In diesem Artikel werden die empfohlenen Tags nach ihrer Verwendung sortiert beschrieben.

Der Compiler überprüft die Syntax der Elemente, die in der folgenden Liste mit einem einzelnen * markiert sind. Visual Studio stellt IntelliSense für die vom Compiler überprüften Tags sowie alle Tags bereit, die in der folgenden Liste durch ** gekennzeichnet sind. Zusätzlich zu den hier aufgeführten Tags überprüfen der Compiler und Visual Studio die Tags <b>, <i>, <u>, <br/> und <a>. Der Compiler überprüft auch <tt>, ein veraltetes HTML-Element.

Hinweis

HTML-Tags wie <br/> sind nützlich für die Formatierung innerhalb von Dokumentationskommentaren. Das <br/> Tag erstellt Zeilenumbrüche, während andere HTML-Tags Textformatierungen bereitstellen. Diese Tags funktionieren in IntelliSense-QuickInfos und in der generierten Dokumentation.

Hinweis

Dokumentationskommentare können nicht auf einen Namespace angewendet werden.

Wenn Sie möchten, dass ein Dokumentationskommentar spitze Klammern enthält, verwenden Sie die HTML-Codierung für < und >: &lt; und &gt;. Diese Codierung wird im folgenden Beispiel gezeigt.

/// <summary>
/// This property always returns a value &lt; 1.
/// </summary>

Allgemeine Tags

<summary>

<summary>description</summary>

Das <summary>-Tag sollte für die Beschreibung eines Typs oder Typmembers verwendet werden. Dient <remarks> zum Hinzufügen von ergänzenden Informationen zu einer Typbeschreibung. Verwenden Sie das cref-Attribut, um Dokumentationswerkzeuge wie DocFX und Sandcastle zum Erstellen von internen Links zu Dokumentationsseiten für Codeelemente zu aktivieren. Der Text für das <summary>-Tag wird in IntelliSense und im Objektbrowserfenster angezeigt.

<remarks>

<remarks>
description
</remarks>

Das <remarks> Tag wird verwendet, um Informationen über einen Typ oder ein Typmemm hinzuzufügen und die angegebenen <summary>Informationen zu ergänzen. Diese Informationen werden im Fenster des Objektkatalogs angezeigt. Dieses Tag kann ausführlichere Erklärungen enthalten. Unter Umständen stellen Sie fest, dass das Schreiben von Markdown mit CDATA-Abschnitten erheblich einfacher wird. Tools wie docfx verarbeiten den Markdowntext in CDATA-Abschnitten.

Dokumentmember

<returns>

<returns>description</returns>

Das <returns>-Tag sollte im Kommentar für eine Methodendeklaration verwendet werden, um den Rückgabewert zu beschreiben.

<param>

<param name="name">description</param>
  • name: Der Name eines Methodenparameters. Setzen Sie den Namen in Anführungszeichen ("). Parameternamen müssen mit der API-Signatur übereinstimmen. Wenn mindestens ein Parameter nicht enthalten ist, gibt der Compiler eine Warnung aus. Der Compiler gibt ebenfalls eine Warnung aus, wenn der Wert von name nicht mit einem formalen Parameter in der Methodendeklaration übereinstimmt.

Das <param>-Tag sollte im Kommentar für eine Methodendeklaration verwendet werden, um einen der Methodenparameter zu beschreiben. Verwenden Sie mehrere <param>-Tags, um mehrere Parameter zu dokumentieren. Der Text für das <param>-Tag wird in IntelliSense, dem Objektkatalog und im Webbericht über Codekommentare angezeigt.

<paramref>

<paramref name="name"/>
  • name: Der Name des Parameters, auf den verwiesen wird. Setzen Sie den Namen in Anführungszeichen (").

Das Tag <paramref> bietet Ihnen eine Möglichkeit anzugeben, dass sich ein Wort in den Codekommentaren, z. B. in einem <summary>- oder <remarks>-Block, auf einen Parameter bezieht. Die XML-Datei kann so verarbeitet werden, dass dieses Wort anders formatiert wird, z.B. fett oder kursiv.

<exception>

<exception cref="member">description</exception>
  • cref = "member": Ein Verweis auf eine Ausnahme, die in der aktuellen Kompilierungsumgebung verfügbar ist. Der Compiler prüft, ob die angegebene Ausnahme vorhanden ist, und übersetzt in der Ausgabe-XML member in den kanonischen Elementnamen. member muss in Anführungszeichen (") eingeschlossen sein.

Mit dem Tag <exception> können Sie angeben, welche Ausnahmen ausgelöst werden können. Dieses Tag kann für Definitionen für Methoden, Eigenschaften, Ereignisse und Indexer angewendet werden.

<value>

<value>property-description</value>

Mit dem <value>-Tag können Sie den Wert beschreiben, den eine Eigenschaft darstellt. Wenn Sie eine Eigenschaft über den Code-Assistenten in der .NET-Entwicklungsumgebung von Visual Studio hinzufügen, wird ein <summary> Tag für die neue Eigenschaft hinzugefügt. Sie fügen manuell ein <value>-Tag für die Beschreibung des Werts hinzu, den die Eigenschaft darstellt.

Formatieren der Dokumentationsausgabe

<para>

<remarks>
    <para>
        This is an introductory paragraph.
    </para>
    <para>
        This paragraph contains more details.
    </para>
</remarks>

Das <para> Tag dient zur Verwendung innerhalb eines Tags, z <summary>. B. , <remarks>oder <returns>, und ermöglicht es Ihnen, dem Text Struktur hinzuzufügen. Das Tag <para> erstellt einen Absatz mit doppeltem Abstand. Verwenden Sie das Tag <br/>, wenn Sie einen Absatz mit einfachem Abstand möchten.

Hier ist ein Beispiel, das den Unterschied zwischen <para> und <br/> zeigt:

/// <summary>
/// Example using para tags:
/// <para>This is the first paragraph.</para>
/// <para>This is the second paragraph with double spacing.</para>
/// 
/// Example using br tags:
/// First line of text<br/>
/// Second line of text with single spacing<br/>
/// Third line of text
/// </summary>
public void FormattingExample()
{
    // This method demonstrates paragraph and line break formatting
}

<list>

<list type="bullet|number|table">
    <listheader>
        <term>term</term>
        <description>description</description>
    </listheader>
    <item>
        <term>Assembly</term>
        <description>The library or executable built from a compilation.</description>
    </item>
</list>

Der <listheader>-Block wird verwendet, um die Überschriftenzeile einer Tabelle oder einer Definitionsliste zu definieren.

Beim Definieren einer Tabelle:

  • müssen nur einen Eintrag für term in der Überschrift angeben.
  • Jedes Element der Liste wird mit einem <item>-Block angegeben. Für jeden item müssen Sie nur einen Eintrag für description angeben.

Beim Erstellen einer Definitionsliste:

  • müssen Sie einen Eintrag für term in der Überschrift angeben.
  • Jedes Element der Liste wird mit einem <item>-Block angegeben. muss jeder item sowohl ein term als auch ein description enthalten.

Eine Liste oder Tabelle kann so viele <item>-Blöcke besitzen wie nötig.

<c>

<c>text</c>

Mit dem <c>-Tag kann angegeben werden, dass Text in einer Beschreibung als Code gekennzeichnet werden soll. Wird verwendet <code> , um mehrere Zeilen als Code anzugeben.

<code>

<code>
    var index = 5;
    index++;
</code>

Mit dem <code>-Tag werden mehrere Codezeilen angegeben. Wird <c> verwendet, um anzugeben, dass einzeiligen Text in einer Beschreibung als Code gekennzeichnet werden soll.

<example>

<example>
This shows how to increment an integer.
<code>
    var index = 5;
    index++;
</code>
</example>

Mit dem <example>-Tag kann ein Beispiel für die Verwendung einer Methode oder eines anderen Bibliothekmembers angegeben werden. Ein Beispiel umfasst häufig die Verwendung des <code> Tags.

<b>

<b>text</b>

Das <b> Tag wird verwendet, um Text in Dokumentationskommentaren fett zu formatieren. Dieses HTML-Tag wird vom Compiler und von Visual Studio validiert, und der formatierte Text wird in IntelliSense und in der generierten Dokumentation angezeigt.

<i>

<i>text</i>

Das <i> Tag wird verwendet, um Text kursiv in Dokumentationskommentaren zu machen. Dieses HTML-Tag wird vom Compiler und von Visual Studio validiert, und der formatierte Text wird in IntelliSense und in der generierten Dokumentation angezeigt.

<u>

<u>text</u>

Das <u> Tag wird verwendet, um Text in Dokumentationskommentaren zu unterstreichen. Dieses HTML-Tag wird vom Compiler und von Visual Studio validiert, und der formatierte Text wird in IntelliSense und in der generierten Dokumentation angezeigt.

<br/>

Line one<br/>Line two

Das <br/> Tag wird verwendet, um einen Zeilenumbruch in Dokumentationskommentare einzufügen. Verwenden Sie dieses Tag, wenn Sie einen Absatz mit einfachem Zeilenabstand möchten, im Gegensatz zu dem <para>-Tag, das Absätze mit doppelten Zeilenabständen erstellt.

<a>

<a href="https://example.com">Link text</a>

Das <a> Tag wird verwendet, um Links in Dokumentationskommentaren zu erstellen. Das href Attribut gibt die URL an, mit der eine Verknüpfung hergestellt werden soll. Dieser HTML-Formatierungs-Tag wird vom Compiler und von Visual Studio überprüft.

Hinweis

Der Compiler überprüft auch das <tt> Tag, das veraltete HTML ist. Verwenden Sie stattdessen das <c> Tag für die Inlinecodeformatierung.

Wiederverwenden des Dokumentationstexts

<inheritdoc>

<inheritdoc [cref=""] [path=""]/>

XML-Kommentare werden aus Basisklassen, Schnittstellen und ähnlichen Methoden geerbt. Durch die Verwendung von inheritdoc wird das unerwünschte Kopieren und Einfügen doppelter XML-Kommentare vermieden, und XML-Kommentare werden automatisch synchronisiert. Wenn Sie einem Typ ein <inheritdoc>-Tag hinzufügen, erben alle Mitglieder auch die Kommentare.

  • cref: Geben Sie den Member an, von dem die Dokumentation geerbt werden soll. Bereits definierte Tags für den aktuellen Member werden nicht von den geerbten überschrieben.
  • path: Die XPath-Ausdrucksabfrage, die dazu führt, dass eine Gruppe von Knoten angezeigt wird. Sie können mit diesem Attribut die Tags filtern, die in der geerbten Dokumentation enthalten oder nicht enthalten sein sollen.

Hinweis

Visual Studio bietet automatische Vererbung von XML-Dokumentation für undokumentierte Member, die dokumentierte Member überschreiben oder implementieren. Dieses Feature zeigt die geerbte Dokumentation in IntelliSense und QuickInfo an, ohne dass das <inheritdoc> Tag erforderlich ist. Diese automatische Vererbung gilt jedoch nur innerhalb der Visual Studio-IDE und wirkt sich nicht auf die vom Compiler generierte XML-Dokumentationsdatei aus.

Für öffentliche APIs in Bibliotheken, die Sie verteilen, sollten Sie das <inheritdoc> Tag explizit verwenden oder eine vollständige Dokumentation bereitstellen, um sicherzustellen, dass die generierte XML-Dokumentationsdatei alle erforderlichen Informationen für Verbraucher Ihrer Bibliothek enthält.

Fügen Sie Ihre XML-Kommentare in Basisklassen oder Schnittstellen hinzu, und lassen Sie die Kommentare von inheritdoc in die implementierenden Klassen kopieren. Fügen Sie Ihre XML-Kommentare zu synchronen Methoden hinzu, und lassen Sie die Kommentare von inheritdoc in die asynchronen Versionen derselben Methoden kopieren. Wenn Sie die Kommentare aus einem bestimmten Member kopieren möchten, geben Sie den Member mithilfe des Attributs cref an.

<include>

<include file='filename' path='tagpath[@name="id"]' />
  • filename: Der Name der XML-Datei, die die Dokumentation enthält. Der Dateiname kann mit einem Pfad relativ zur Quellcodedatei qualifiziert werden. filename muss in einfache Anführungszeichen (‚‘) eingeschlossen werden.
  • tagpath: Der Pfad der Tags in filename, der zum Tag name führt. Der Pfad muss in einfache Anführungszeichen (‚‘) eingeschlossen werden.
  • name: Der Namensbezeichner in dem Tag, das vor den Kommentaren steht. name besitzt ein id-Element.
  • id: Die ID des Tags, das vor den Kommentaren steht. Setzen Sie die ID in Anführungszeichen (").

Mit dem <include>-Tag können Sie auf Kommentare in einer anderen Datei verweisen, in denen die Typen und Member in Ihrem Quellcode beschrieben werden. Das Aufnehmen einer externen Datei ist eine Alternative zum direkten Platzieren von Dokumentationskommentaren in der Quellcodedatei. Durch das Ablegen der Dokumentation in einer separaten Datei können Sie die Quellcodeverwaltung unabhängig vom Quellcode auf die Dokumentation anwenden. Eine Person kann die Quellcodedatei auschecken, eine andere die Dokumentationsdatei. Das Tag <include> verwendet die XML-XPath-Syntax. Weitere Anpassungsmöglichkeiten bei der Verwendung von <include> finden Sie in der XPath-Dokumentation.

Im folgenden Quellcode wird z. B. das <include>-Tag verwendet, um Hinweise einzuschließen. Der Dateipfad ist relativ zur Quelle.

namespace MyNamespace;

public class MyType
{
    /// <returns>This is the returns text of MyMethod. It comes from triple slash comments.</returns>
    /// <remarks>This is the remarks text of MyMethod. It comes from triple slash comments.</remarks>
    /// <include file="MyAssembly.xml" path="doc/members/member[@name='M:MyNamespace.MyType.MyMethod']/*" />
    public int MyMethod(int p) => p;
}

Die XML-Quelle für die include-Datei wird im folgenden Beispiel gezeigt. Sie ist identisch mit der XML-Datei, die vom C#-Compiler generiert wird. Die XML-Datei kann Text für mehrere Methoden oder Typen enthalten, solange ein XPath-Ausdruck sie identifizieren kann.

<?xml version="1.0"?>
<doc>
    <members>
        <member name="M:MyNamespace.MyType.MyMethod">
            <param name="p">This is the description of the parameter p of MyMethod. It comes from the included file.</param>
            <summary>This is the summary of MyMethod. It comes from the included file.</summary>
        </member>
    </members>
</doc>

Die XML-Ausgabe für diese Methode wird im folgenden Beispiel gezeigt:

<member name="M:MyNamespace.MyType.MyMethod(System.Int32)">
    <summary>This is the summary of MyMethod. It comes from the included file.</summary>
    <returns>This is the returns text of MyMethod. It comes from triple slash comments.</returns>
    <remarks>This is the remarks text of MyMethod. It comes from triple slash comments.</remarks>
    <param name="p">This is the description of the parameter p of MyMethod. It comes from the included file.</param>
</member>

Tipp

Das .NET-Runtime-Team verwendet das <include>-Tag sehr häufig in der Dokumentation. Sie finden viele Beispiele, wenn Sie das dotnet/runtime-Repository durchsuchen.

<see>

<see cref="member"/>
<!-- or -->
<see cref="member">Link text</see>
<!-- or -->
<see href="link">Link Text</see>
<!-- or -->
<see langword="keyword"/>
  • cref="member": Ein Verweis auf einen Member oder ein Feld, das in der aktuellen Kompilierungsumgebung aufgerufen werden kann. Der Compiler überprüft, ob das angegebene Codeelement vorhanden ist, und übergibt member an den Elementnamen in der XML-Ausgabe. Setzen Sie member in Anführungszeichen ("). Sie können einen anderen Linktext für ein "cref"-Attribut angeben, indem Sie ein separates schließendes Tag verwenden.
  • href="link": Ein klickbarer Link zu einer bestimmten URL. <see href="https://github.com">GitHub</see> erzeugt beispielsweise einen Link, auf den geklickt werden kann und der den Text GitHub aufweist. Er führt zu https://github.com. Verwenden Sie href anstelle von cref beim Verlinken mit externen Webseiten, da cref für Codeverweise vorgesehen ist und keine klickbaren Links für externe URLs erstellt.
  • langword="keyword": Ein Schlüsselwort der Sprache, z. B. true, oder eines der anderen gültigen Schlüsselwörter.

Mit dem <see>-Tag kann ein Link im Text angegeben werden. Wird <seealso> verwendet, um anzugeben, dass Text in einem Abschnitt "Siehe auch" platziert werden soll. Verwenden Sie das cref-Attribut, um interne Links zu Dokumentationsseiten für Codeelemente zu erstellen. Sie fügen die Typparameter ein, um einen Verweis auf einen generischen Typen oder eine generische Methode anzugeben, z. B. cref="IDictionary{T, U}". Außerdem ist href ein gültiges Attribut, das als Hyperlink fungiert.

Hier ist ein Beispiel, das den Unterschied zwischen cref und href dem Verweisen auf externe URLs zeigt:

/// <summary>
/// This method demonstrates URL linking:
/// <see cref="https://learn.microsoft.com/dotnet/csharp"/> (won't create clickable link)
/// <see href="https://learn.microsoft.com/dotnet/csharp">C# documentation</see> (creates clickable link)
/// </summary>
public void UrlLinkingExample()
{
    // This method demonstrates the difference between cref and href for URLs
}

<seealso>

<seealso cref="member"/>
<!-- or -->
<seealso href="link">Link Text</seealso>
  • cref="member": Ein Verweis auf einen Member oder ein Feld, das in der aktuellen Kompilierungsumgebung aufgerufen werden kann. Der Compiler überprüft, ob das angegebene Codeelement vorhanden ist, und übergibt member an den Elementnamen in der XML-Ausgabe. member muss in Anführungszeichen (") eingeschlossen sein.
  • href="link": Ein klickbarer Link zu einer bestimmten URL. <seealso href="https://github.com">GitHub</seealso> erzeugt beispielsweise einen Link, auf den geklickt werden kann und der den Text GitHub aufweist. Er führt zu https://github.com.

Mit dem Tag <seealso> können Sie den Text angeben, der im Abschnitt Siehe auch angezeigt werden soll. Wird <see> verwendet, um einen Link aus Text anzugeben. Das Tag seealso kann nicht in das Tag summary geschachtelt werden.

cref-Attribut

Das Attribut cref in einem XML-Dokumentationstag bedeutet „Codeverweis“. Es gibt an, dass der innere Text des Tags ein Codeelement ist, z. B. ein Typ, eine Methode oder Eigenschaft. Dokumentationstools wie DocFX und Sandcastle verwenden die cref-Attribute zum automatischen Generieren von Hyperlinks auf der Seite, auf der der Typ oder Member dokumentiert wird.

href-Attribut

Das href-Attribut steht für einen Verweis auf eine Webseite. Sie können damit direkt auf die Onlinedokumentation zu Ihrer API oder Bibliothek verweisen. Wenn Sie zu externen URLs in Ihren Dokumentationskommentaren verlinken müssen, verwenden Sie href anstelle von cref, damit die Links in IntelliSense-QuickInfos und generierten Dokumentationen anklickbar sind.

Generische Typen und Methoden

<typeparam>

<typeparam name="TResult">The type returned from this method</typeparam>
  • TResult: Der Name des Typparameters. Setzen Sie den Namen in Anführungszeichen (").

Die <typeparam> -Tag sollte im Kommentar für einen generischen Typ oder eine Methodendeklaration verwendet werden, um einen Typparameter zu beschreiben. Fügen Sie ein Tag für jeden Typparameter des generischen Typs oder der Methode hinzu. Der Text für das Tag <typeparam> wird in IntelliSense angezeigt.

<typeparamref>

<typeparamref name="TKey"/>
  • TKey: Der Name des Typparameters. Setzen Sie den Namen in Anführungszeichen (").

Verwenden Sie dieses Tag, um Consumern der Dokumentationsdatei zu ermöglichen, das Wort auf unterschiedliche Weise zu formatieren, z.B. in Kursivschrift.

Benutzerdefinierter Tags

Alle in diesem Artikel genannten Tags werden vom C#-Compiler erkannt. Ein Benutzer kann jedoch auch eigene Tags definieren. Tools wie Sandcastle unterstützen zusätzliche Tags wie <event> und <note>unterstützen sogar dokumentierende Namespaces. Benutzerdefinierte oder interne Dokumentationsgenerierungstools können auch mit den Standardtags verwendet werden, und mehrere Ausgabeformate von HTML in PDF können unterstützt werden.

  • Last updated on