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.

Toto upozornění můžete povolit v souboru projektu přidáním <WarnOn> elementu do oddílu <PropertyGroup> :

<WarnOn>3390</WarnOn>

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.

Poznámka:

Pokud použijete komentáře bez značek XML, nebudou žádné značky, které zahrnete (například značky HTML nebo syntaxe podobné jazyku XML), analyzovány ani kontrolovány kompilátorem ani nástroji jazyka F#. Některé externí nástroje, jako je GitHub, se můžou pokusit analyzovat značky, ale pokud syntaxe obsahuje chyby, může selhat. Pokud potřebujete v dokumentaci použít značky XML, zabalte komentáře se správnými značkami XML, aby <summary> se zajistilo, že --warnon:3390 jsou při povolení ověřeny kompilátorem.

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ý přístup 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

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."
<include file="path.xml" path="XPath"/> Počínaje kompilátorem F# 11 obsahuje vybrané elementy XML z externího souboru vygenerované dokumentace.
<inheritdoc/> Požadavky zděděné dokumentace z kompatibilních nástrojů Značka zůstává ve formátu XML generovaném kompilátorem.

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=" odkaz">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 fsdocs přinášejí podporu pro další značky, 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

Opakované použití a dědění dokumentace

Pokud chcete zachovat sdílené poznámky jednou, umístěte je shared.xml vedle zdroje:

<docs>
  <tracking>
    <remarks>An unrecognized tracking identifier has status Unknown.</remarks>
  </tracking>
</docs>

Oba členy vyberou tyto prvky se stejným výrazem XPath:

/// <summary>Find the latest status of a shipment.</summary>
/// <include file="shared.xml" path="/docs/tracking/*"/>
let status trackingId =
    if trackingId = "SHP-1042" then "Dispatched" else "Unknown"

/// <summary>Find the latest statuses of several shipments.</summary>
/// <include file="shared.xml" path="/docs/tracking/*"/>
let statuses trackingIds =
    trackingIds |> List.map (fun id -> id, status id)

Povolit GenerateDocumentationFile nebo předat --doc:Tracking.xml. Od F# 11 obsahují vygenerované položky vybrané poznámky a místní souhrny, nejen značky.

Ukázkový projekt sleduje XML jako vstup kompilace, takže upravuje regeneraci triggeru. Nevyžaduje se výslovný souhlas s jazykovou verzí. Zahrnuje rozbalení ve vygenerovaném XML, nikoli v živých rychlých informacích.

Zahrnutí řešení a chyb

Relativní názvy souborů se nejprve přeloží na adresář zdrojového souboru a pak do pracovního adresáře kompilátoru. Vnořené zahrnuje překlad vzhledem k jejich obsahujícímu souboru XML. Vyberte prvky, například /docs/tracking/*místo textu nebo uzlů atributů.

Chybějící soubory, poškozený kód XML, neplatná cesta XPath a cykly vytvářejí diagnostiku. Platná cesta XPath bez shody zachová značku a přidá komentář bez upozornění. Zpracování DTD a externí překlad XML jsou zakázány; elementy cizího oboru názvů include zůstávají běžným obsahem. Viz referenční informace<include> o syntaxi XPath.

Zděděná dokumentace v nástrojích

Pokud se chcete vyhnout kopírování popisu základního člena do každého přepsání, použijte <inheritdoc/>:

[<AbstractClass>]
type TrackingBase() =
    /// <summary>Find the latest status of a shipment.</summary>
    abstract Status: trackingId: string -> string

type TrackingService() =
    inherit TrackingBase()
    /// <inheritdoc/>
    override _.Status trackingId = status trackingId

Nástroje F# 11 a FSharp.Compiler.Service zveřejňují zděděný popis pro TrackingService.Status. Kompilátor ponechá <inheritdoc/> v generovaném KÓDU XML, aby mohl interpretovat podřízené nástroje. Aktualizace samotného jádra neaktualizuje překladač editoru.

Použijte nejvyšší úroveň <inheritdoc/>, ne značku vnořenou uvnitř <summary>. Explicitní cref, konstruktory a případy křížového sestavení nebo křížového sestavení závisí na příjemci dokumentace. Použijte úplné identifikátory dokumentace XML a zkontrolujte cílový nástroj. Viz referenční informace<inheritdoc>.

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.

  • Před F# 11 kompilátor zkopíruje <include> , aniž by ho rozbalil. <inheritdoc> stále vyžaduje, aby příjemce dokumentace vyřešil zděděný obsah, jak je popsáno v tématu Opětovné použití a dědění dokumentace.

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

  • Poslední aktualizace v