Uw code documenteer met XML-opmerkingen

Artikel
03/12/2024

U kunt documentatie maken uit drievoudige slash-codeopmerkingen (///) in F#. XML-opmerkingen kunnen voorafgaan aan declaraties in codebestanden (.fs) of handtekeningbestanden (.fsi).

Xml-documentatieopmerkingen zijn een speciaal soort opmerking, toegevoegd boven de definitie van een door de gebruiker gedefinieerd type of lid. Ze zijn speciaal omdat ze door de compiler kunnen worden verwerkt om tijdens het compileren een XML-documentatiebestand te genereren. Het door de compiler gegenereerde XML-bestand kan naast uw .NET-assembly worden gedistribueerd, zodat IDE's knopinfo kunnen gebruiken om snelle informatie over typen of leden weer te geven. Daarnaast kan het XML-bestand worden uitgevoerd via hulpprogramma's zoals fsdocs om API-referentiewebsites te genereren.

XML-documentatieopmerkingen, zoals alle andere opmerkingen, worden genegeerd door de compiler, tenzij de hieronder beschreven opties zijn ingeschakeld om de geldigheid en volledigheid van opmerkingen tijdens het compileren te controleren.

U kunt het XML-bestand tijdens het compileren genereren door een van de volgende handelingen uit te voeren:

U kunt een GenerateDocumentationFile element toevoegen aan de <PropertyGroup> sectie van het .fsproj projectbestand, waarmee een XML-bestand in de projectmap wordt gegenereerd met dezelfde hoofdbestandsnaam als de assembly. Voorbeeld:
```
<GenerateDocumentationFile>true</GenerateDocumentationFile>
```
Zie de eigenschap GenerateDocumentationFile voor meer informatie.
Als u een toepassing ontwikkelt met Visual Studio, klikt u met de rechtermuisknop op het project en selecteert u Eigenschappen. Selecteer in het dialoogvenster Eigenschappen het tabblad Opbouwen en controleer het XML-documentatiebestand. U kunt ook de locatie wijzigen waarop de compiler het bestand schrijft.

Er zijn twee manieren om xml-documentatieopmerkingen te schrijven: met en zonder XML-tags. Beide maken gebruik van drievoudige slash-opmerkingen.

Opmerkingen zonder XML-tags

Als een /// opmerking niet begint met een <, wordt de hele tekst van de opmerking genomen als de samenvattingsdocumentatie voor de codeconstructie die direct volgt. Gebruik deze methode als u slechts een korte samenvatting voor elke constructie wilt schrijven.

De opmerking wordt tijdens het voorbereiden van de documentatie gecodeerd naar XML, dus tekens zoals <, >en & hoeven niet te worden ontsnapt. Als u niet expliciet een samenvattingstag opgeeft, moet u geen andere tags opgeven, zoals param of tags retourneren.

In het volgende voorbeeld ziet u de alternatieve methode, zonder XML-tags. In dit voorbeeld wordt de hele tekst in de opmerking beschouwd als een samenvatting.

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

Opmerkingen met XML-tags

Als een hoofdtekst van een opmerking begint met < (normaal <summary>gesproken), wordt deze behandeld als een hoofdtekst van een xml-opgemaakte opmerking met behulp van XML-tags. Op deze tweede manier kunt u afzonderlijke notities opgeven voor een korte samenvatting, aanvullende opmerkingen, documentatie voor elke parameter en typeparameter en uitzonderingen die zijn gegenereerd, en een beschrijving van de retourwaarde.

Hier volgt een typische opmerking in xml-documentatie in een handtekeningbestand:

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

Aanbevolen tags

Als u XML-tags gebruikt, worden in de volgende tabel de buitenste tags beschreven die worden herkend in opmerkingen bij F#XML-code.

Tagsyntaxis	Beschrijving
`<summary>`*tekst*`</summary>`	Hiermee geeft u op dat tekst een korte beschrijving van het programma-element is. De beschrijving is meestal een of twee zinnen.
`<remarks>`*tekst*`</remarks>`	Hiermee geeft u op dat tekst aanvullende informatie bevat over het programma-element.
`<param name="`*naambeschrijving*`"></param>`	Hiermee geeft u de naam en beschrijving voor een functie of methodeparameter.
`<typeparam name="`*naambeschrijving*`"></typeparam>`	Hiermee geeft u de naam en beschrijving voor een typeparameter.
`<returns>`*tekst*`</returns>`	Hiermee geeft u op dat tekst de retourwaarde van een functie of methode beschrijft.
`<exception cref="`*typebeschrijving*`"></exception>`	Hiermee geeft u het type uitzondering op dat kan worden gegenereerd en de omstandigheden waaronder deze wordt gegenereerd.
`<seealso cref="`*Verwijzing*`"/>`	Hiermee geeft u een koppeling Zie ook naar de documentatie voor een ander type. De verwijzing is de naam zoals deze wordt weergegeven in het XML-documentatiebestand. Zie Ook worden koppelingen meestal onderaan een documentatiepagina weergegeven.

In de volgende tabel worden de tags beschreven voor gebruik in beschrijvingssecties:

Tagsyntaxis	Beschrijving
`<para>`*tekst*`</para>`	Hiermee geeft u een alinea met tekst op. Dit wordt gebruikt om tekst binnen de opmerkingentag te scheiden.
`<code>`*tekst*`</code>`	Hiermee geeft u op dat tekst meerdere regels code is. Deze tag kan worden gebruikt door documentatiegeneratoren om tekst weer te geven in een lettertype dat geschikt is voor code.
`<paramref name="`*name*`"/>`	Hiermee geeft u een verwijzing naar een parameter in dezelfde documentatie opmerking.
`<typeparamref name="`*name*`"/>`	Hiermee geeft u een verwijzing naar een typeparameter in dezelfde documentatie-opmerking.
`<c>`*tekst*`</c>`	Hiermee geeft u op dat tekst inlinecode is. Deze tag kan worden gebruikt door documentatiegeneratoren om tekst weer te geven in een lettertype dat geschikt is voor code.
`<see cref="`*verwijzingstekst*`"></see>`	Hiermee geeft u een inline-koppeling naar een ander programma-element. De verwijzing is de naam zoals deze wordt weergegeven in het XML-documentatiebestand. De tekst is de tekst die in de koppeling wordt weergegeven.

Door de gebruiker gedefinieerde tags

De vorige tags vertegenwoordigen de tags die worden herkend door de F#-compiler en typische F#-editorhulpprogramma's. Een gebruiker is echter vrij om hun eigen tags te definiëren. Hulpprogramma's zoals fsdocs bieden ondersteuning voor extra tags, zoals namespacedoc>.< Aangepaste of interne hulpprogramma's voor het genereren van documentatie kunnen ook worden gebruikt met de standaardtags en meerdere uitvoerindelingen van HTML naar PDF kunnen worden ondersteund.

Tijdcontrole compileren

Wanneer --warnon:3390 deze optie is ingeschakeld, controleert de compiler de syntaxis van de XML en de parameters waarnaar wordt verwezen in <param> en <paramref> tags.

F#-constructies documenteren

F#-constructies zoals modules, leden, samenvoegcases en recordvelden worden beschreven door een /// opmerking direct voorafgaand aan hun declaratie. Indien nodig worden impliciete constructors van klassen gedocumenteerd door een /// opmerking te geven vóór de lijst met argumenten. Voorbeeld:

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

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

Beperkingen

Sommige functies van XML-documentatie in C# en andere .NET-talen worden niet ondersteund in F#.

In F# moeten kruisverwijzingen bijvoorbeeld de volledige XML-handtekening van het bijbehorende symbool cref="T:System.Console"gebruiken. Eenvoudige C#-stijl kruisverwijzingen, zoals cref="Console" niet worden uitgebreid naar volledige XML-handtekeningen en deze elementen worden niet gecontroleerd door de F#-compiler. Bij sommige documentatiehulpprogramma's kan het gebruik van deze kruisverwijzingen worden toegestaan door de volgende verwerking, maar de volledige handtekeningen moeten worden gebruikt.
De tags <include>worden <inheritdoc> niet ondersteund door de F#-compiler. Er wordt geen fout weergegeven als ze worden gebruikt, maar ze worden gewoon gekopieerd naar het gegenereerde documentatiebestand zonder dat dit van invloed is op de gegenereerde documentatie.
Kruisverwijzingen worden niet gecontroleerd door de F#-compiler, zelfs niet wanneer -warnon:3390 ze worden gebruikt.
De namen die worden gebruikt in de tags <typeparam> en <typeparamref> worden niet gecontroleerd door de F#-compiler, zelfs niet wanneer --warnon:3390 ze worden gebruikt.
Er worden geen waarschuwingen gegeven als er documentatie ontbreekt, zelfs wanneer --warnon:3390 deze wordt gebruikt.

Aanbevelingen

Documenteringscode wordt om verschillende redenen aanbevolen. Hier volgen enkele aanbevolen procedures, algemene use-casescenario's en dingen die u moet weten wanneer u XML-documentatietags gebruikt in uw F#-code.

Schakel de optie --warnon:3390 in uw code in om ervoor te zorgen dat uw XML-documentatie geldige XML is.
Overweeg om handtekeningbestanden toe te voegen om lange XML-documentatieopmerkingen van uw implementatie te scheiden.
In het belang van consistentie moeten alle openbaar zichtbare typen en hun leden worden gedocumenteerd. Als je het moet doen, doe het dan allemaal.
Minimaal moeten modules, typen en hun leden een lege /// opmerking of <summary> tag hebben. Dit wordt weergegeven in een venster met knopinfo voor automatisch aanvullen in F#-bewerkingsprogramma's.
De documentatietekst moet worden geschreven met volledige zinnen die eindigen op volledige stops.