Dokumentace XML (F#)
Dokumentace z triple lomítko (/ / /) můžete vytvářet poznámky v F# kódu.Komentáře XML lze předcházet prohlášení v kódu soubory (.fs) nebo podpis (.fsi).
Generování dokumentace z komentáře
Podpora F# pro generování dokumentace z komentáře je stejný jako v ostatních.NET Framework jazyky.Jako v ostatních.NET Framework jazyky -volba kompilátoru doc umožňuje vytvořit soubor XML obsahující informace, které lze převést do dokumentace pomocí nástroje, jako je například Sandcastle.V dokumentaci generované pomocí nástroje, které jsou navrženy pro použití s obložením, které jsou zapsány v jiných.NET Framework jazyky obecně vyrábět zobrazení rozhraní API, která je založena na kompilované formě F# konstrukce.Pokud nástroje konkrétně podporují F#, generované tyto nástroje dokumentace neodpovídá zobrazení F# rozhraní API.
Další informace o způsobu generování dokumentace z XML naleznete v tématu Dokumentační komentáře XML (Průvodce programováním v C#).
Doporučené značky
Existují dva způsoby zápisu komentářů dokumentace XML.Jeden je právě dokumentaci psát přímo do komentáře triple lomítko, bez použití značky XML.Je-li to provést, je celý komentář za souhrnnou dokumentaci konstrukce kódu, která následuje ihned.Tuto metodu použijte, když chcete napsat stručný souhrn pro každou konstrukci.Další metodou je použití značky XML poskytnout více strukturované dokumentaci.Druhá metoda umožňuje určit samostatné poznámky pro krátký souhrn, další poznámky, dokumentaci pro každý parametr a parametr typu a výjimek vyvolaných a popis návratové hodnoty.Následující tabulka popisuje značek XML, které jsou rozpoznány v komentáři kódu XML F#.
Syntaxe značek |
Description |
|---|---|
<c>text</c> |
Určuje, že textu kód.Tato značka slouží generátory dokumentace k zobrazení textu v písmu pro příslušný kód. |
<summary>text</summary> |
Určuje, že textu je stručný popis prvku programu.Popis je obvykle jednu nebo dvě věty. |
<remarks>text</remarks> |
Určuje, že textu obsahuje doplňující informace o prvku programu. |
<param name="name"> description</param> |
Určuje název a popis pro parametr funkce nebo metody. |
<typeparam name="name"> description </typeparam> |
Určuje název a popis pro parametr typu. |
<returns>text</returns> |
Určuje, že textu popisuje vrácenou hodnotu funkce nebo metody. |
<exception cref="type">description</exception> |
Určuje typ výjimky, které mohou být generovány a okolnosti, za kterých je vyvolána. |
<see cref="reference">text</see> |
Určuje propojení vloženého prvku jiný program.Referenční je název je zobrazen v soubor dokumentace XML.Textu je text zobrazen v odkazu. |
<seealso cref="odkaz"/> |
Určuje odkaz Viz také v dokumentaci k jinému typu.Referenční je název je zobrazen v soubor dokumentace XML.Viz také odkazy, které jsou obvykle zobrazeny v dolní části stránky dokumentaci. |
<para>text</para> |
Určuje odstavec textu.Slouží k oddělení textu uvnitř remarks značky. |
Příklad
Description
Následuje typický komentář dokumentace XML v souboru.
Kód
/// <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
Příklad
Description
Následující příklad ukazuje alternativní metody bez značky XML.V tomto příkladu je celý text komentáře považována za souhrn.Poznámka: Pokud souhrnné označení explicitně nezadáte, by není určit jiné značky, například param nebo returns značky.
Kód
/// 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