Zdokumentujte kód pomocí komentářů XML

Můžete vytvořit dokumentaci z komentářů kódu /// (trojité lomítko) v jazyce F#. Komentáře XML můžou předcházet deklaracím v souborech kódu (.fs) nebo v souborech signatur (.fsi).

Komentáře dokumentace XML jsou speciálním druhem komentáře, který je přidán nad definici libovolného uživatelem definovaného typu nebo člena. Jsou speciální, protože kompilátor je může zpracovat za účelem vygenerování souboru dokumentace XML v době kompilace. Soubor XML vygenerovaný kompilátorem lze distribuovat společně se sestavením .NET, aby IDE mohly pomocí tipů zobrazit rychlé informace o typech nebo členech. Kromě toho lze soubor XML spustit pomocí nástrojů, jako je fsdocs generovat referenční weby rozhraní API.

Ve výchozím nastavení kompilátor ignoruje komentáře dokumentace XML. Pokud to chcete změnit, nastavte --warnon:3390. Kompilátor pak ověří syntaxi XML a parametrů uvedených v <param> a <paramref> značkách.

Soubor XML můžete vygenerovat v době kompilace jedním z následujících způsobů:

• Do GenerateDocumentationFile části souboru projektu <PropertyGroup> můžete přidat prvek .fsproj, který vygeneruje soubor XML v adresáři projektu se stejným kořenovým názvem souboru jako sestavení. Například:

  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  

  Další informace naleznete ve vlastnosti GenerateDocumentationFile.

• Pokud vyvíjíte aplikaci pomocí sady Visual Studio, klikněte pravým tlačítkem myši na projekt a vyberte Vlastnosti. V dialogovém okně vlastností vyberte kartu Sestavení a zkontrolujte soubor dokumentace XML. Můžete také změnit umístění, do kterého kompilátor zapisuje soubor.

Existují dva způsoby, jak psát komentáře dokumentace XML: se značkami XML a bez značek XML. Oba používají trojité lomítkové komentáře.

Komentáře bez značek XML

Pokud komentář /// nezačíná <, celý text komentáře se považuje za souhrnnou dokumentaci pro konstrukci kódu, která bezprostředně následuje. Tuto metodu použijte, pokud chcete pro každou konstrukci napsat pouze stručný souhrn.

Komentář se během přípravy dokumentace zakóduje do XML, takže znaky, jako jsou <, >a &, nemusí být escapovány. Pokud explicitně nezadáte souhrnnou značku, neměli byste zadávat další značky, jako například param nebo značky returns.

Následující příklad ukazuje alternativní metodu bez značek XML. V tomto příkladu se celý text v komentáři považuje za souhrn.

/// 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

Komentáře se značkami XML

Pokud text komentáře začíná < (obvykle <summary>), považuje se za text komentáře ve formátu XML pomocí značek XML. Tento druhý způsob umožňuje zadat samostatné poznámky pro krátký souhrn, další poznámky, dokumentaci pro každý vyvolaný parametr a parametr typu a výjimky a popis návratové hodnoty.

Následuje typický komentář dokumentace XML v souboru podpisu:

/// <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

Doporučené značky

Pokud používáte značky XML, následující tabulka popisuje vnější značky rozpoznané v komentářích kódu XML jazyka F#.

Syntaxe značek	Popis
<summary> text</summary>	Určuje, že text je stručný popis prvku programu. Popis je obvykle jedna nebo dvě věty.
<remarks> text</remarks>	Určuje, že text obsahuje doplňující informace o prvku programu.
<param name=" "> popis</param>	Určuje název a popis parametru funkce nebo metody.
<typeparam name=" "> popis</typeparam>	Určuje název a popis parametru typu.
<returns> text</returns>	Určuje, že text popisuje návratovou hodnotu funkce nebo metody.
<exception cref=" typu">popis</exception>	Určuje typ výjimky, kterou lze vygenerovat, a okolnosti, za kterých je vyvolán.
<seealso cref=" referenční"/>	Určuje odkaz na část 'Viz také' v dokumentaci pro jiný typ. Reference je název tak, jak se objevuje v souboru dokumentace XML. "Odkazy See Also se obvykle zobrazují v dolní části stránky dokumentace."

Následující tabulka popisuje značky pro použití v částech popisu:

Syntaxe značek	Popis
<para> text</para>	Určuje odstavec textu. Slouží k oddělení textu uvnitř poznámek značky.
<code> text</code>	Určuje, že text je více řádků kódu. Tuto značku můžou používat generátory dokumentace k zobrazení textu v písmu, které je vhodné pro kód.
<paramref name=" název"/>	Určuje odkaz na parametr ve stejném komentáři dokumentace.
<typeparamref name=" název"/>	Určuje odkaz na parametr typu ve stejném komentáři dokumentace.
<c> text</c>	Určuje, že text je vložený kód. Tuto značku můžou používat generátory dokumentace k zobrazení textu v písmu, které je vhodné pro kód.
<see cref=" reference">text</see>	Určuje vložený odkaz na jiný prvek programu. Reference je název tak, jak se objevuje v souboru dokumentace XML. Text je text zobrazený na odkazu.

Uživatelsky definované značky

Předchozí značky představují ty, které kompilátor jazyka F# rozpozná a typické nástroje editoru jazyka F#. Nicméně, uživatelé mohou definovat své vlastní značky. Nástroje, jako je fsdocs, přinášejí podporu dalších značek, jako je <namespacedoc>. Vlastní nebo interní nástroje pro generování dokumentace lze také použít se standardními značkami a více výstupních formátů z HTML do PDF lze podporovat.

Kontrola času kompilace

Pokud je povolen --warnon:3390, kompilátor ověří syntaxi XML a parametry uvedené v <param> a značkách <paramref>.

Dokumentace konstrukcí jazyka F#

Konstrukty jazyka F#, jako jsou moduly, členy, případy sjednocení a pole záznamů, jsou dokumentovány /// komentářem bezprostředně před jejich deklarací. V případě potřeby jsou implicitní konstruktory tříd zdokumentované zadáním /// komentáře před seznamem argumentů. Například:

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

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

Omezení

Některé funkce dokumentace XML v jazyce C# a jiných jazycích .NET nejsou v jazyce F# podporované.

• V jazyce F# musí křížové odkazy používat úplný podpis XML odpovídajícího symbolu, například cref="T:System.Console". Jednoduché křížové odkazy ve stylu jazyka C#, jako je cref="Console", nejsou propracované na úplné podpisy XML a kompilátor jazyka F# tyto prvky nekontroluje. Některé nástroje dokumentace mohou umožnit použití těchto křížových odkazů následným zpracováním, ale měly by se použít úplné podpisy.

• Kompilátor jazyka F# nepodporuje značky <include>, <inheritdoc>. Pokud se používají, nezobrazí se žádná chyba, ale jednoduše se zkopírují do vygenerovaného souboru dokumentace, aniž by jinak ovlivnily vygenerovanou dokumentaci.

• Kompilátor jazyka F# nekontroluje křížové odkazy ani v případě, že -warnon:3390 použijete.

• Názvy používané ve značkách <typeparam> a <typeparamref> nejsou kompilátorem jazyka F# kontrolovány, i když se používá --warnon:3390.

• Pokud chybí dokumentace, nejsou k dispozici žádná upozornění, i když --warnon:3390 použijete.

Doporučení

Dokumentování kódu se doporučuje z mnoha důvodů. Následuje několik osvědčených postupů, scénářů obecného použití a věcí, které byste měli vědět při použití značek dokumentace XML v kódu jazyka F#.

• Povolte v kódu možnost --warnon:3390, abyste měli jistotu, že je dokumentace XML platná.

• Zvažte přidání souborů podpisu k oddělení dlouhých komentářů dokumentace XML od implementace.

• Kvůli konzistenci by měly být zdokumentovány všechny veřejně viditelné typy a jejich členy. Pokud to musíte udělat, udělejte to všechno.

• Na minimum by moduly, typy a jejich členy měly mít prostý /// komentář nebo značku <summary>. Zobrazí se v okně popisu automatického dokončování v nástrojích pro úpravy jazyka F#.

• Text dokumentace by měl být napsán pomocí úplných vět končících úplnými zarážkami.

Viz také

• Komentáře k dokumentaci XML v C# (Průvodce programováním v C#).
• referenční příručka k jazyku F#
• možnosti kompilátoru