Dokumentieren von Code mit XML-Kommentaren

Artikel
03/10/2023

Sie können in F# eine Dokumentation aus Codekommentaren mit drei Schrägstrichen (///) erstellen. XML-Kommentare können Deklarationen in Codedateien (.fs) oder Signaturdateien (.fsi) vorangestellt werden.

XML-Dokumentationskommentare sind eine besondere Art von Kommentaren, die über der Definition von benutzerdefinierten Typen oder Membern hinzugefügt werden. Sie sind besonders, da sie vom Compiler verarbeitet werden können, um eine XML-Dokumentationsdatei zur Kompilierzeit zu generieren. Die vom Compiler generierte XML-Datei kann zusammen mit Ihrer .NET-Assembly verteilt werden, sodass integrierte Entwicklungsumgebungen QuickInfos verwenden können, um schnelle Informationen über Typen oder Mitglieder anzuzeigen. Darüber hinaus kann die XML-Datei mithilfe von Tools wie fsdocs ausgeführt werden, um API-Verweiswebsites zu generieren.

XML-Dokumentationskommentare werden wie alle anderen Kommentare vom Compiler ignoriert, es sei denn, die unten beschriebenen Optionen sind aktiviert, um die Gültigkeit und Vollständigkeit von Kommentaren zur Kompilierzeit zu überprüfen.

Sie können die XML-Datei zur Kompilierzeit generieren, indem Sie eine der folgenden Aktionen durchführen:

Sie können ein GenerateDocumentationFile-Element in den <PropertyGroup>-Abschnitt Ihrer .fsproj-Projektdatei einfügen, das eine XML-Datei im Projektverzeichnis mit demselben Stammdateinamen wie die Assembly generiert. Beispiel:
```
<GenerateDocumentationFile>true</GenerateDocumentationFile>
```
Weitere Informationen finden Sie unter GenerateDocumentationFile-Eigenschaft.
Wenn Sie eine Anwendung mit Visual Studio entwickeln, klicken Sie mit der rechten Maustaste auf das Projekt, und wählen Sie Eigenschaften aus. Wählen Sie im Eigenschaftendialogfeld die Registerkarte Erstellen aus, und aktivieren Sie das Kontrollkästchen bei XML-Dokumentationsdatei. Sie können auch den Speicherort ändern, an den der Compiler die Datei schreibt.

Es gibt zwei Möglichkeiten zum Schreiben von XML-Dokumentationskommentaren: mit und ohne XML-Tags. Beide kennzeichnen Kommentare durch drei Schrägstriche.

Kommentare ohne XML-Tags

Wenn ein ///-Kommentar nicht mit einem < beginnt, wird der gesamte Kommentartext als Zusammenfassungsdokumentation für das Codekonstrukt übernommen, das unmittelbar folgt. Verwenden Sie diese Methode, wenn Sie nur eine kurze Zusammenfassung für jedes Konstrukt schreiben möchten.

Der Kommentar wird während der Dokumentationsvorbereitung in XML codiert, sodass Zeichen wie <, > und & nicht mit Escapezeichen versehen werden müssen. Wenn Sie kein Zusammenfassungstag explizit angeben, sollten Sie keine anderen Tags angeben, z. B. param- oder returns-Tags.

Das folgende Beispiel zeigt die alternative Methode ohne XML-Tags. In diesem Beispiel wird der gesamte Text im Kommentar als Zusammenfassung betrachtet.

/// Creates a new string whose characters are the result of applying
/// the function mapping to each of the characters of the input string
/// and concatenating the resulting strings.
val collect : (char -> string) -> string -> string

Kommentare mit XML-Tags

Wenn ein Kommentartext mit < (normalerweise <summary>) beginnt, wird er als XML-formatierter Kommentartext mit XML-Tags behandelt. Diese zweite Möglichkeit ermöglicht es Ihnen, separate Notizen für eine kurze Zusammenfassung, zusätzliche Bemerkungen, eine Dokumentation für jeden Parameter und jeden Typparameter sowie für ausgelöste Ausnahmen und eine Beschreibung des Rückgabewerts anzugeben.

Es folgt ein typischer XML-Dokumentationskommentar in einer Signaturdatei:

/// <summary>Builds a new string whose characters are the results of applying the function <c>mapping</c>
/// to each of the characters of the input string and concatenating the resulting
/// strings.</summary>
/// <param name="mapping">The function to produce a string from each character of the input string.</param>
///<param name="str">The input string.</param>
///<returns>The concatenated string.</returns>
///<exception cref="System.ArgumentNullException">Thrown when the input string is null.</exception>
val collect : (char -> string) -> string -> string

Empfohlene Tags

Wenn Sie XML-Tags verwenden, beschreibt die folgende Tabelle die äußeren Tags, die in XML-Codekommentaren von F# erkannt werden.

Tagsyntax	BESCHREIBUNG
`<summary>`*text*`</summary>`	Gibt an, dass text eine kurze Beschreibung des Programmelements ist. Die Beschreibung umfasst in der Regel ein oder zwei Sätze.
`<remarks>`*text*`</remarks>`	Gibt an, dass text ergänzende Informationen zum Programmelement enthält.
`<param name="`*name`">`description*`</param>`	Gibt den Namen und die Beschreibung für einen Funktions- oder Methodenparameter an.
`<typeparam name="`*name`">`description*`</typeparam>`	Gibt den Namen und die Beschreibung für einen Typparameter an.
`<returns>`*text*`</returns>`	Gibt an, dass text den Rückgabewert einer Funktion oder Methode beschreibt.
`<exception cref="`*type`">`description*`</exception>`	Gibt die Art der Ausnahme an, die generiert werden kann, und die Umstände, unter denen sie ausgelöst wird.
`<seealso cref="`*reference*`"/>`	Gibt einen „Siehe auch“-Link zu der Dokumentation für einen anderen Typ an. Die reference-Instanz ist der Name, wie er in der XML-Dokumentationsdatei angezeigt wird. „Siehe auch“-Links werden normalerweise am Ende einer Dokumentationsseite angezeigt.

In der folgenden Tabelle werden die Tags für die Verwendung in Beschreibungsabschnitten beschrieben:

Tagsyntax	BESCHREIBUNG
`<para>`*text*`</para>`	Gibt einen Textabsatz an. Dies wird verwendet, um Text innerhalb des remarks-Tags zu trennen.
`<code>`*text*`</code>`	Gibt an, dass text mehrere Codezeilen umfasst. Dieses Tag kann von Dokumentationsgeneratoren verwendet werden, um Text in einer für den Code geeigneten Schriftart anzuzeigen.
`<paramref name="`*name*`"/>`	Gibt einen Verweis auf einen Parameter in demselben Dokumentationskommentar an.
`<typeparamref name="`*name*`"/>`	Gibt einen Verweis auf einen Typparameter in demselben Dokumentationskommentar an.
`<c>`*text*`</c>`	Gibt an, dass text Inlinecode ist. Dieses Tag kann von Dokumentationsgeneratoren verwendet werden, um Text in einer für den Code geeigneten Schriftart anzuzeigen.
`<see cref="`*reference`">`text*`</see>`	Gibt einen Inlinelink zu einem anderen Programmelement an. Die reference-Instanz ist der Name, wie er in der XML-Dokumentationsdatei angezeigt wird. Die text-Instanz ist der im Link angezeigte Text.

Benutzerdefinierter Tags

Die vorherigen Tags sind diejenigen, die vom F#-Compiler und den typischen F#-Editor-Tools erkannt werden. Ein Benutzer kann jedoch auch eigene Tags definieren. Tools wie fsdocs bieten Unterstützung für zusätzliche Tags wie <namespacedoc>. Benutzerdefinierte oder interne Dokumentationsgenerierungstools können auch mit den Standardtags verwendet werden, und mehrere Ausgabeformate von HTML in PDF können unterstützt werden.

Überprüfung zur Kompilierzeit

Wenn --warnon:3390 aktiviert ist, überprüft der Compiler die Syntax des XML-Codes und die Parameter, auf die in <param>- und <paramref>-Tags verwiesen werden.

Dokumentieren von F#-Konstrukten

F#-Konstrukte wie Module, Member, Union-Fälle und Datensatzfelder werden unmittelbar vor der Deklaration durch einen ///-Kommentar dokumentiert. Bei Bedarf werden implizite Konstruktoren von Klassen dokumentiert, indem vor der Argumentliste ein ///-Kommentar angegeben wird. Beispiel:

/// This is the type
type SomeType
      /// This is the implicit constructor
      (a: int, b: int) =

    /// This is the member
    member _.Sum() = a + b

Einschränkungen

Einige Features der XML-Dokumentation in C# und anderen .NET-Sprachen werden in F# nicht unterstützt.

In F# müssen Querverweise die vollständige XML-Signatur des entsprechenden Symbols verwenden, z. B. cref="T:System.Console". Einfache Querverweise im C#-Stil wie cref="Console" werden nicht zu vollständigen XML-Signaturen ausgearbeitet und diese Elemente werden vom F#-Compiler nicht überprüft. Einige Dokumentationstools können die Verwendung dieser Querverweise durch nachträgliche Bearbeitung ermöglichen, aber es sollten die vollständigen Signaturen verwendet werden.
Die Tags <include>, <inheritdoc> werden vom F#-Compiler nicht unterstützt. Es wird kein Fehler ausgegeben, wenn sie verwendet werden, sondern sie werden einfach in die generierte Dokumentationsdatei kopiert, ohne die generierte Dokumentation anderweitig zu beeinflussen.
Querverweise werden vom F#-Compiler nicht überprüft, auch wenn -warnon:3390 verwendet wird.
Die in den Tags <typeparam> und <typeparamref> verwendeten Namen werden vom F#-Compiler nicht überprüft, auch wenn --warnon:3390 verwendet wird.
Es werden keine Warnungen angezeigt, wenn die Dokumentation fehlt, auch wenn --warnon:3390 verwendet wird.

Empfehlungen

Das Dokumentieren von Code wird aus vielen Gründen empfohlen. Es folgen einige bewährte Methoden, allgemeine Anwendungsfallszenarios und Dinge, die Sie wissen sollten, wenn Sie XML-Dokumentationstags in Ihrem F#-Code verwenden.

Aktivieren Sie die Option --warnon:3390 in Ihrem Code, um sicherzustellen, dass Ihre XML-Dokumentation gültiger XML-Code ist.
Erwägen Sie das Hinzufügen von Signaturdateien, um lange XML-Dokumentationskommentare von Ihrer Implementierung zu trennen.
Aus Gründen der Konsistenz sollten alle öffentlich sichtbaren Typen und deren Member dokumentiert werden. Tun Sie dies wenn nötig vollständig.
Mindestens sollten Module, Typen und ihre Member über einen einfachen ///-Kommentar oder ein <summary>-Tag verfügen. Dies wird in einem QuickInfo-Fenster für die automatische Vervollständigung in den F#-Bearbeitungstools angezeigt.
Dokumentationstext sollte in vollständigen Sätze geschrieben werden, die mit Punkten enden.