Dokumentera koden med XML-kommentarer

Artikel
12/18/2024

Du kan skapa dokumentation från trippel-snedstreck (///) kodkommentarer i F#. XML-kommentarer kan föregå deklarationer i kodfiler (.fs) eller signaturfiler (.fsi).

XML-dokumentationskommentare är en särskild typ av kommentar som läggs till ovanför definitionen av någon användardefinierad typ eller medlem. De är speciella eftersom de kan bearbetas av kompilatorn för att generera en XML-dokumentationsfil vid kompileringstillfället. Den kompilatorgenererade XML-filen kan distribueras tillsammans med din .NET-sammansättning så att IDE:er kan använda knappbeskrivningar för att visa snabb information om typer eller medlemmar. Dessutom kan XML-filen köras via verktyg som fsdocs för att generera API-referenswebbplatser.

Som standard ignoreras XML-dokumentationskommentarer av kompilatorn. Om du vill ändra detta anger du --warnon:3390. Kompilatorn verifierar sedan syntaxen för XML och de parametrar som anges i taggarna <param> och <paramref>.

Du kan generera XML-filen vid kompileringstillfället genom att göra något av följande:

Du kan lägga till ett GenerateDocumentationFile-element i avsnittet <PropertyGroup> i din .fsproj projektfil, som genererar en XML-fil i projektkatalogen med samma rotfilnamn som sammansättningen. Till exempel:
```
<GenerateDocumentationFile>true</GenerateDocumentationFile>
```
Mer information finns i egenskapen GenerateDocumentationFile.
Om du utvecklar ett program med Visual Studio högerklickar du på projektet och väljer Egenskaper. I dialogrutan Egenskaper väljer du fliken Skapa och markerar XML-dokumentationsfil. Du kan också ändra platsen som kompilatorn skriver filen till.

Det finns två sätt att skriva XML-dokumentationskommentar: med och utan XML-taggar. Båda använder kommentarer med tre snedstreck.

Kommentarer utan XML-taggar

Om en /// kommentar inte börjar med en <tas hela kommentarstexten som sammanfattningsdokumentation för kodkonstruktionen som omedelbart följer. Använd den här metoden om du bara vill skriva en kort sammanfattning för varje konstruktion.

Kommentaren kodas till XML under förberedelsen av dokumentationen, så tecken som <, >och & behöver inte vara undantagna. Om du inte uttryckligen anger en sammanfattningstagg bör du inte ange andra taggar, till exempel param- eller returnerar taggar.

I följande exempel visas den alternativa metoden utan XML-taggar. I det här exemplet betraktas hela texten i kommentaren som en sammanfattning.

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

Kommentarer med XML-taggar

Om en kommentarstext börjar med < (normalt <summary>) behandlas den som en XML-formaterad kommentarstext med XML-taggar. På det här andra sättet kan du ange separata anteckningar för en kort sammanfattning, ytterligare kommentarer, dokumentation för varje parameter och typparameter och undantag som genereras samt en beskrivning av returvärdet.

Följande är en typisk XML-dokumentationskommentare i en signaturfil:

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

Rekommenderade taggar

Om du använder XML-taggar beskriver följande tabell de yttre taggar som identifieras i F# XML-kodkommenterar.

Taggsyntax	Beskrivning
`<summary>` *text*`</summary>`	Anger att text är en kort beskrivning av programelementet. Beskrivningen är vanligtvis en eller två meningar.
`<remarks>` *text*`</remarks>`	Anger att text innehåller ytterligare information om programelementet.
`<param name="` *namn`">`beskrivning*`</param>`	Anger namnet och beskrivningen för en funktions- eller metodparameter.
`<typeparam name="` *namn`">`beskrivning*`</typeparam>`	Anger namn och beskrivning för en typparameter.
`<returns>` *text*`</returns>`	Anger att text beskriver returvärdet för en funktion eller metod.
`<exception cref="` *typ`">`beskrivning*`</exception>`	Anger vilken typ av undantag som kan genereras och under vilka omständigheter det genereras.
`<seealso cref="` *referens*`"/>`	Anger en "Se även"-länk till dokumentationen för en annan typ. Referensen är namnet som visas i XML-dokumentationsfilen. Se Även länkar visas vanligtvis längst ned på en dokumentationssida.

I följande tabell beskrivs taggarna för användning inuti beskrivningsavsnitt:

Taggsyntax	Beskrivning
`<para>` *text*`</para>`	Anger ett stycke text. Detta används för att avgränsa text i taggen kommentarer.
`<code>` *text*`</code>`	Anger att text är flera rader kod. Den här taggen kan användas av dokumentationsgeneratorer för att visa text i ett teckensnitt som är lämpligt för kod.
`<paramref name="` *namn*`"/>`	Anger en referens till en parameter i samma dokumentationskommentare.
`<typeparamref name="` *namn*`"/>`	Anger en referens till en typparameter i samma dokumentationskommentare.
`<c>` *text*`</c>`	Anger att text är inline-kod. Den här taggen kan användas av dokumentationsgeneratorer för att visa text i ett teckensnitt som är lämpligt för kod.
`<see cref="` *referens`">`text*`</see>`	Anger en infogad länk till ett annat programelement. -referensen är namnet som det framgår i XML-dokumentationsfilen. Den texten är den text som visas i länken.

Användardefinierade taggar

De tidigare taggarna representerar de som identifieras av F#-kompilatorn och vanliga F#-redigeringsverktyg. En användare kan dock definiera sina egna taggar. Verktyg som fsdocs ger stöd för extra taggar som <namespacedoc>. Anpassade eller interna verktyg för dokumentationsgenerering kan också användas med standardtaggar och flera utdataformat från HTML till PDF kan stödjas.

Kompileringstidskontroll

När --warnon:3390 är aktiverat verifierar kompilatorn syntaxen för XML och de parametrar som anges i taggarna <param> och <paramref>.

Dokumentera F#-konstruktioner

F#-konstruktioner som moduler, medlemmar, unionstyper och registerfält dokumenteras av en ///-kommentar omedelbart före deklarationen. Om det behövs dokumenteras implicita konstruktorer av klasser genom att ge en /// kommentar före argumentlistan. Till exempel:

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

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

Begränsningar

Vissa funktioner i XML-dokumentationen i C# och andra .NET-språk stöds inte i F#.

I F#måste korsreferenser använda den fullständiga XML-signaturen för motsvarande symbol, till exempel cref="T:System.Console". Enkla korsreferenser i C#-format, till exempel cref="Console" inte är utvecklade för fullständiga XML-signaturer och dessa element kontrolleras inte av F#-kompilatorn. Vissa dokumentationsverktyg kan tillåta användning av dessa korsreferenser genom efterföljande bearbetning, men de fullständiga signaturerna bör användas.
Taggarna <include>, <inheritdoc> stöds inte av F#-kompilatorn. Inget fel anges om de används, men de kopieras helt enkelt till den genererade dokumentationsfilen utan att på annat sätt påverka den genererade dokumentationen.
Korsreferenser kontrolleras inte av F#-kompilatorn, inte ens när -warnon:3390 används.
Namnen som används i taggarna <typeparam> och <typeparamref> kontrolleras inte av F#-kompilatorn, inte ens när --warnon:3390 används.
Inga varningar ges om dokumentation saknas, även när --warnon:3390 används.

Rekommendationer

Dokumenteringskod rekommenderas av många orsaker. Följande är några metodtips, scenarier för allmänna användningsfall och saker som du bör känna till när du använder XML-dokumentationstaggar i din F#-kod.

Aktivera alternativet --warnon:3390 i koden för att säkerställa att XML-dokumentationen är giltig XML.
Överväg att lägga till signaturfiler för att separera långa XML-dokumentationskommentarer från implementeringen.
För konsekvensens skull bör alla offentligt synliga typer och deras medlemmar dokumenteras. Om du måste göra det, gör allt.
Moduler, typer och deras medlemmar bör åtminstone ha en enkel ///-kommentar eller <summary>-tagg. Detta visas i ett verktygstipsfönster för automatiskt ifyllande i F#-redigeringsverktyg.
Dokumentationstexten ska skrivas med fullständiga meningar som slutar med fullständiga stopp.

Dela via