Zdokumentujte kód pomocí komentářů XML

Článek
03/12/2024

Dokumentaci můžete vytvořit 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 je možné distribuovat společně s sestavením .NET, aby idE mohly pomocí popisů zobrazit rychlé informace o typech nebo členech. Kromě toho lze soubor XML spustit pomocí nástrojů, jako je fsdocs, aby se vygenerovaly referenční weby rozhraní API.

Komentáře dokumentace XML, stejně jako všechny ostatní komentáře, jsou kompilátorem ignorovány, pokud nejsou povoleny možnosti popsané níže ke kontrole platnosti a úplnosti komentářů v době kompilace.

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

Do oddílu <PropertyGroup>.fsproj souboru projektu můžete přidat GenerateDocumentationFile prvek, který vygeneruje soubor XML v adresáři projektu se stejným kořenovým názvem souboru jako sestavení. Příklad:
```
<GenerateDocumentationFile>true</GenerateDocumentationFile>
```
Další informace naleznete v GenerateDocumentationFile vlastnost.
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ítko.

Komentáře bez značek XML

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

Komentář se během přípravy dokumentace zakóduje do XML, takže znaky, jako <je , >a & nemusí být uchycené. Pokud explicitně nezadáte souhrnnou značku, neměli byste zadávat jiné značky, jako jsou parametry nebo vrací značky.

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>), pak se považuje 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 názvu*`"></param>`	Určuje název a popis parametru funkce nebo metody.
`<typeparam name="`*popis názvu*`"></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="`*popis typu*`"></exception>`	Určuje typ výjimky, kterou lze vygenerovat, a okolnosti, za kterých je vyvolán.
`<seealso cref="`*Odkaz*`"/>`	Určuje odkaz Viz také na dokumentaci pro jiný typ. Odkaz je název, který se zobrazí v souboru dokumentace XML. Viz Odkazy Také 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ř značky poznámek .
`<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="`*Jméno*`"/>`	Určuje odkaz na parametr ve stejném komentáři dokumentace.
`<typeparamref name="`*Jméno*`"/>`	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="`*referenční`">`text*`</see>`	Určuje vložený odkaz na jiný prvek programu. Odkaz je název, který se zobrazí v souboru dokumentace XML. Text je text zobrazený v 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#. Uživatel ale může definovat 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 --warnon:3390 je povoleno, kompilátor ověří syntaxi XML a parametrů uvedených v <param> a <paramref> značkách.

Dokumentace konstruktorů jazyka F#

Konstrukty jazyka F#, jako jsou moduly, členy, sjednocovací případy a pole záznamů, jsou zdokumentované 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ů. Pří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#, například 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.
Značky <include><inheritdoc> kompilátor jazyka F# nepodporují. 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ě -warnon:3390 použití.
Názvy používané ve značkách <typeparam> a <typeparamref> kompilátor jazyka F# nejsou kontrolovány, i když --warnon:3390 se používají.
Žádná upozornění se nezobrazují, pokud chybí dokumentace, i když --warnon:3390 se používá.

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 , která vám pomůže zajistit, aby dokumentace XML byla 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 <summary> značku. 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.

Sdílet prostřednictvím