Dokumentera koden med XML-kommentarer

Artikel
03/05/2024

Du kan skapa dokumentation från trippel-snedstreck (///) kodkommentar 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 .

XML-dokumentationskommentarer, liksom alla andra kommentarer, ignoreras av kompilatorn, såvida inte alternativen som beskrivs nedan är aktiverade för att kontrollera giltigheten och fullständigheten av kommentarer vid kompileringstiden.

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 <PropertyGroup> avsnittet i .fsproj projektfilen, 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 kontrollerar XML-dokumentationsfilen. 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 returnera 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 texten innehåller ytterligare information om programelementet.
`<param name="`*namnbeskrivning*`"></param>`	Anger namnet och beskrivningen för en funktions- eller metodparameter.
`<typeparam name="`*namnbeskrivning*`"></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="`*typbeskrivning*`"></exception>`	Anger vilken typ av undantag som kan genereras och under vilka omständigheter det genereras.
`<seealso cref="`*Referens*`"/>`	Anger länken Se även till dokumentationen för en annan typ. Referensen är namnet som det 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 kommentarstaggen.
`<code>`*text*`</code>`	Anger att text är flera rader med 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 texten är infogad 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="`*referenstext*`"></see>`	Anger en infogad länk till ett annat programelement. Referensen är namnet som det visas i XML-dokumentationsfilen. 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 <param> och <paramref> taggarna.

Dokumentera F#-konstruktioner

F#-konstruktioner som moduler, medlemmar, fackliga ärenden och postfä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 som 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 den 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 ha en enkel /// kommentar eller <summary> tagg som minimum. Detta visas i ett knappbeskrivningsfönster för automatisk komplettering i F#-redigeringsverktyg.
Dokumentationstexten ska skrivas med fullständiga meningar som slutar med fullständiga stopp.

Share via