Uw code documenteer met XML-opmerkingen

Artikel
12/18/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 worden standaard genegeerd door de compiler. Als u dit wilt wijzigen, stelt u --warnon:3390in. De compiler controleert vervolgens de syntaxis van de XML en de parameters waarnaar wordt verwezen in <param> en <paramref> tags.

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 sectie <PropertyGroup> van het .fsproj projectbestand, waarmee een XML-bestand in de projectmap wordt gegenereerd met dezelfde hoofdbestandsnaam als de assembly. Bijvoorbeeld:
```
<GenerateDocumentationFile>true</GenerateDocumentationFile>
```
Voor meer informatie, zie eigenschap GenerateDocumentationFile.
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 Build 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 opmerkingen met drie schuine strepen.

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, zodat tekens zoals <, >en & niet hoeven te worden geëscaped. Als u niet expliciet een samenvattingstag opgeeft, moet u geen andere tags opgeven, zoals param- of tags retourneert.

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 gesproken <summary>), wordt deze behandeld als een xml-opgemaakte hoofdtekst van een opmerking met 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.

Tag-syntax	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="` *naam`">`beschrijving*`</param>`	Hiermee geeft u de naam en beschrijving voor een functie of methodeparameter.
`<typeparam name="` *naam`">`beschrijving*`</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="` `">` *beschrijving*`</exception>`	Hiermee geeft u het type uitzondering op dat kan worden gegenereerd en de omstandigheden waaronder deze wordt gegenereerd.
`<seealso cref="` `"/>`	Specificeert een Zie ook-koppeling 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 in de opmerkingen tag te scheiden.
`<code>` *tekst*`</code>`	Hiermee geeft u op dat tekst uit meerdere regels code bestaat. Deze tag kan worden gebruikt door documentatiegeneratoren om tekst weer te geven in een lettertype dat geschikt is voor code.
`<paramref name="` *naam*`"/>`	Hiermee geeft u een verwijzing naar een parameter in dezelfde documentatie opmerking.
`<typeparamref name="` *naam*`"/>`	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="` *referentie`">`tekst*`</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 <naamruimtedoc>. 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.

Controle tijdens het compileren

Wanneer --warnon:3390 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, uniegevallen en recordvelden worden gedocumenteerd door een ///-commentaar direct voorafgaand aan hun declaratie. Indien nodig worden impliciete constructors van klassen gedocumenteerd door een /// opmerking te geven vóór de lijst met argumenten. Bijvoorbeeld:

/// 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 de volledige XML-handtekening van het bijbehorende symbool gebruiken, bijvoorbeeld cref="T:System.Console". Eenvoudige C#-stijl kruisverwijzingen zoals cref="Console" worden niet 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>, <inheritdoc> worden 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 wordt gebruikt.
De namen die worden gebruikt in de tags <typeparam> en <typeparamref> worden niet gecontroleerd door de F#-compiler, zelfs niet wanneer --warnon:3390 wordt gebruikt.
Er worden geen waarschuwingen gegeven als er documentatie ontbreekt, zelfs wanneer --warnon:3390 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.
Modules, typen en hun leden zouden op zijn minst een eenvoudig /// commentaar of <summary> tag moeten 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.

Delen via