Dokumentieren Sie den Code mit XML-Kommentaren

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) vorangehen.

XML-Dokumentationskommentare sind eine spezielle Art von Kommentar, die oberhalb der Definition eines benutzerdefinierten Typs oder Elements hinzugefügt wird. Sie sind besonders, da sie vom Compiler verarbeitet werden können, um während der Kompilierung eine XML-Dokumentationsdatei zu generieren. Die vom Compiler generierte XML-Datei kann zusammen mit Ihrer .NET-Assembly verteilt werden, damit IDEs Tooltipps verwenden können, um schnelle Informationen zu Typen oder Mitgliedern anzuzeigen. Darüber hinaus kann die XML-Datei über Tools wie fsdocs ausgeführt werden, um API-Referenzwebsites zu generieren.

Standardmäßig werden XML-Dokumentationskommentare vom Compiler ignoriert. Legen Sie --warnon:3390fest, um dies zu ändern. Der Compiler überprüft dann die Syntax des XML-Codes und die Parameter, auf die in <param> und <paramref> Tags verwiesen wird.

Sie können die XML-Datei während der Kompilierung generieren, indem Sie eine der folgenden Aktionen ausführen:

• Sie können dem Abschnitt <PropertyGroup> Ihrer .fsproj Projektdatei ein GenerateDocumentationFile-Element hinzufügen, das eine XML-Datei im Projektverzeichnis mit demselben Stammdateinamen wie die Assembly generiert. Zum 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 Eigenschaftenaus. 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, in 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 F#-XML-Codekommentaren erkannt werden.

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

Benutzerdefinierte Tags

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

Überprüfung zur Kompilierzeit

Wenn --warnon:3390 aktiviert ist, überprüft der Compiler die Syntax des XML-Codes und die Parameter, die in <param>- und <paramref>-Tags bezeichnet 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. Zum Beispiel:

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

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

Begrenzungen

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 C#-Querverweise wie cref="Console" werden nicht für vollständige 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, aber sie werden einfach in die generierte Dokumentationsdatei kopiert, ohne dass sich dies auf die generierte Dokumentation auswirkt.

• Querverweise werden vom F#-Compiler nicht überprüft, auch wenn -warnon:3390 verwendet wird.

• Die in den Tags verwendeten Namen <typeparam> und <typeparamref> 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 ist aus vielen Gründen empfehlenswert. Es folgen einige bewährte Methoden, allgemeine Anwendungsfallszenarien und Dinge, die Sie bei der Verwendung von XML-Dokumentationstags in Ihrem F#-Code wissen sollten.

• Aktivieren Sie die Option --warnon:3390 in Ihrem Code, um sicherzustellen, dass Ihre XML-Dokumentation gültiges XML 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 ihre Mitglieder dokumentiert werden. Wenn Sie dies tun müssen, tun Sie alles.

• 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.

Weitere Informationen

• C#-XML-Dokumentationskommentare (C#-Programmierhandbuch).
• F#-Sprachreferenz
• Compileroptionen