XML-Dokumentation (F#)
Sie können Dokumentation in F# aus Dreifachschrägstrich(///)-Codekommentaren erzeugen. XML-Kommentare können Deklarationen in Codedateien (FS-Format) oder Signaturdateien (FSI-Format) vorausgehen.
Generieren von Dokumentation aus Kommentaren
Das Generieren von Dokumentation aus Kommentaren wird in F# auf die gleiche Weise wie in anderen .NET Framework-Sprachen unterstützt. Wie in anderen .NET Framework-Sprachen ermöglicht die -DOC-Compileroption die Erzeugung einer XML-Datei mit Informationen, die mit einem Tool, z. B. Sandcastle, in eine Dokumentation konvertiert werden können. Die mit Tools, die zur Verwendung mit Assemblys in anderen .NET Framework-Sprachen entworfen wurden, generierte Dokumentation, erzeugt im Allgemeinen eine Ansicht der APIs, die auf der kompilierten Form von F#-Konstrukten basieren. Außer wenn die Tools ausdrücklich F# unterstützen, stimmt die mit diesen Tools generierte Dokumentation nicht mit der F#-Ansicht einer API überein.
Weitere Informationen zum Generieren von Dokumentation aus XML finden Sie unter XML-Dokumentationskommentare (C#-Programmierhandbuch).
Empfohlene Tags
Für das Schreiben von Kommentaren zur XML-Dokumentation gibt es zwei Möglichkeiten. Zum Einen können Sie ohne die Verwendung von XML-Tags die Dokumentation direkt in einen Dreifachschrägstrichkommentar schreiben. Bei dieser Vorgehensweise wird der gesamte Kommentartext als Zusammenfassungsdokumentation für das Codekonstrukt verarbeitet, das sofort folgt. Verwenden Sie diese Methode, wenn Sie nur eine kurze Zusammenfassung für jedes Konstrukt verfassen möchten. Zum Anderen können Sie XML-Tags verwenden, um strukturiertere Dokumentation bereitzustellen. Mit der zweiten Methode können Sie separate Hinweise für eine kurze Zusammenfassung, weitere Hinweise, Dokumentation für einzelne Parameter, Typparameter und ausgelöste Ausnahmen sowie eine Beschreibung des Rückgabewerts angeben. In der folgenden Tabelle werden XML-Tags beschrieben, die in F#-XML-Codekommentaren erkannt werden.
Tagsyntax |
Beschreibung |
|---|---|
<c> Text </c> |
Gibt an, dass Text Code ist. Dieses Tag kann von Dokumentationsgeneratoren verwendet werden, um Text in einer für Code geeigneten Schriftart anzuzeigen. |
<summary> Text </summary> |
Gibt an, dass Text eine kurze Beschreibung des Programmelements ist. Die Beschreibung umfasst normalerweise ein oder zwei Sätze. |
<remarks> Text </remarks> |
Gibt an, dass Text zusätzliche Informationen zum Programmelement enthält. |
<param name="Name"> Beschreibung </param> |
Gibt den Namen und die Beschreibung für eine Funktion oder einen Methodenparameter an. |
<typeparam name="Name"> Beschreibung </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 einer Methode beschreibt. |
<exception cref="Typ"> Beschreibung </exception> |
Gibt den Ausnahmetyp, der generiert werden kann, und die Umstände an, unter denen die Ausnahme ausgelöst wird. |
<see cref="Verweis"> Text </see> |
Gibt einen Inlinelink zu einem anderen Programmelement an. Der Verweis ist der Name, wie er in der XML-Dokumentationsdatei angezeigt wird. Der Text ist der im Link angezeigte Text. |
<seealso cref="-Referenz"/> |
Gibt einen "Siehe auch"-Link zur Dokumentation eines anderen Typs an. Der Verweis ist der Name, wie er in der XML-Dokumentationsdatei angezeigt wird. "Siehe auch"-Links werden normalerweise am unteren Rand einer Dokumentationsseite angezeigt. |
<para> Text </para> |
Gibt einen Textabsatz an. Dieser wird verwendet, um Text im remarks-Tag zu trennen. |
Beispiel
Beschreibung
Der Folgende ist ein typischer XML-Dokumentationskommentar in einer Signaturdatei.
Code
/// <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
Beispiel
Beschreibung
Im folgenden Beispiel wird die alternative Methode ohne XML-Tags veranschaulicht. In diesem Beispiel wird der gesamte Kommentartext als Zusammenfassung betrachtet. Wenn Sie kein Zusammenfassungstag explizit angeben, sollten Sie keine anderen Tags angeben, z. B. das param-Tag oder returns-Tag.
Code
/// 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