Freigeben über

Empfohlene XML-Tags für C#-Dokumentationskommentare

  • Artikel

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

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. Verwenden Sie <remarks>, um zusätzliche Informationen zu einer Typbeschreibung hinzuzufügen. 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>

Mit dem Tag <remarks> werden Informationen zu einem Typ oder Typmember hinzugefügt. Dadurch werden die mit <summary> angegebenen Informationen ergänzt. 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. Beim Hinzufügen einer Eigenschaft über den Code-Assistenten in der Visual Studio .NET-Entwicklungsumgebung wird für die neue Eigenschaft ein <summary>-Tag 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 Tag <para> ist für die Verwendung innerhalb eines Tags wie <summary>, <remarks> oder <returns> gedacht und ermöglicht es Ihnen, den Text zu strukturieren. Das Tag <para> erstellt einen Absatz mit doppeltem Abstand. Verwenden Sie das Tag <br/>, wenn Sie einen Absatz mit einfachem Abstand möchten.

<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. Zum Angeben mehrerer Zeilen als Code wird <code> verwendet.

<code>

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

Mit dem <code>-Tag werden mehrere Codezeilen angegeben. Verwenden Sie <c>, um anzugeben, dass einzeiliger 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 schließt im Allgemeinen die Verwendung des <code>-Tags ein.

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.

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.
  • 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. Verwenden Sie <seealso>, um anzugeben, dass Text in einen Abschnitt „Siehe auch“ eingefügt 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.

<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. Mit <see> kann ein Link im Text angegeben werden. 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.

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 bieten Unterstützung für zusätzliche Tags wie <event> und <note> und unterstützen sogar das Dokumentieren von 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.