Aanbevolen XML-tags voor opmerkingen bij C#-documentatie

Opmerkingen bij C#-documentatie maken gebruik van XML-elementen om de structuur van de uitvoerdocumentatie te definiëren. Een gevolg van deze functie is dat u elke geldige XML in uw documentatieopmerkingen kunt toevoegen. De C#-compiler kopieert deze elementen naar het XML-uitvoerbestand. Hoewel u elke geldige XML in uw opmerkingen (inclusief een geldig HTML-element) kunt gebruiken, wordt documentcode om verschillende redenen aanbevolen.

De C#-taalreferentiedocumenten de laatst uitgebrachte versie van de C#-taal. Het bevat ook de eerste documentatie voor functies in openbare previews voor de aanstaande taalrelease.

De documentatie identificeert alle functies die voor het eerst zijn geïntroduceerd in de laatste drie versies van de taal of in de huidige openbare previews.

Hieronder volgen enkele aanbevelingen, algemene use-casescenario's en dingen die u moet weten wanneer u XML-documentatietags gebruikt in uw C#-code. Hoewel u tags in uw documentatieopmerkingen kunt plaatsen, worden in dit artikel de aanbevolen tags voor de meest voorkomende taalconstructies beschreven. Houd u aan deze aanbevelingen:

• Documenteer alle openbaar zichtbare typen en hun openbare leden, omwille van consistentie.
• U kunt ook privéleden documenteren met behulp van XML-opmerkingen. Deze benadering toont echter de interne (mogelijk vertrouwelijke) werking van uw bibliotheek.
• Minimaal moeten typen en hun leden een <summary> tag hebben.
• Schrijf documentatietekst met volledige zinnen die eindigen op volledige stops.
• Gedeeltelijke klassen worden volledig ondersteund en documentatiegegevens worden samengevoegd tot één vermelding voor elk type. Als beide declaraties van een gedeeltelijk lid documentatieopmerkingen hebben, worden de opmerkingen over de implementatiedeclaratie naar de uitvoer-XML geschreven.

XML-documentatie begint met ///. Wanneer u een nieuw project maakt, worden in de sjablonen enkele starterslijnen /// voor u geplaatst. De verwerking van deze opmerkingen heeft enkele beperkingen:

• De documentatie moet een goed opgemaakte XML zijn. Als de XML niet goed is opgemaakt, genereert de compiler een waarschuwing. Het documentatiebestand bevat een opmerking met de mededeling dat er een fout is opgetreden.
• Sommige van de aanbevolen tags hebben speciale betekenissen:
  • De <param> tag beschrijft parameters. Als u deze tag gebruikt, controleert de compiler of de parameter bestaat en of alle parameters worden beschreven in de documentatie. Als de verificatie mislukt, geeft de compiler een waarschuwing.
  • Koppel het cref kenmerk aan een tag om te verwijzen naar een code-element. De compiler controleert of dit code-element bestaat. Als de verificatie mislukt, geeft de compiler een waarschuwing. De compiler respecteert alle using instructies wanneer wordt gezocht naar een type dat in het cref kenmerk wordt beschreven.
  • IntelliSense in Visual Studio gebruikt de <summary> tag om aanvullende informatie weer te geven over een type of lid.

    Notitie

    Het XML-bestand bevat geen volledige informatie over het type en de leden (het bevat bijvoorbeeld geen typegegevens). Als u volledige informatie wilt over een type of lid, gebruikt u het documentatiebestand samen met weerspiegeling van het werkelijke type of lid.

• Ontwikkelaars kunnen hun eigen set tags maken. De compiler kopieert deze tags naar het uitvoerbestand.

Sommige van de aanbevolen tags kunnen worden gebruikt voor elk taalelement. Anderen hebben meer gespecialiseerd gebruik. Ten slotte worden sommige tags gebruikt om tekst in uw documentatie op te maken. In dit artikel worden de aanbevolen tags beschreven die zijn ingedeeld op basis van hun gebruik.

De compiler controleert de syntaxis van de elementen, gevolgd door één * in de volgende lijst. Visual Studio biedt IntelliSense voor de tags die zijn geverifieerd door de compiler en alle tags gevolgd door ** in de volgende lijst. Naast de tags die hier worden vermeld, valideert de compiler en Visual Studio de <b>tags , <i><u>, <br/>en <a> tags. De compiler valideert <tt>ook, wat afgeschafte HTML is.

• Algemene tags die worden gebruikt voor meerdere elementen: deze tags zijn de minimale set voor elke API.
  • <summary>: De waarde van dit element wordt weergegeven in IntelliSense in Visual Studio.
  • <remarks> **
• Tags die worden gebruikt voor leden : deze tags worden gebruikt bij het documenteren van methoden en eigenschappen.
  • <returns>: De waarde van dit element wordt weergegeven in IntelliSense in Visual Studio.
  • <param> *: De waarde van dit element wordt weergegeven in IntelliSense in Visual Studio.
  • <paramref>
  • <exception> *
  • <value>: De waarde van dit element wordt weergegeven in IntelliSense in Visual Studio.
• Uitvoer van documentatie opmaken: deze tags bieden opmaakrichtingen voor hulpprogramma's die documentatie genereren.
  • <para>
  • <list>
  • <c>
  • <code>
  • <example> **
  • <b>
  • <i>
  • <u>
  • <br/>
  • <a>
• Documentatietekst hergebruiken: deze tags bieden hulpprogramma's waarmee u XML-opmerkingen gemakkelijker kunt hergebruiken.
  • <inheritdoc> **
  • <include> *
• Koppelingen en verwijzingen genereren: deze tags genereren koppelingen naar andere documentatie.
  • <see> *
  • <seealso> *
  • cref
  • href
• Tags voor algemene typen en methoden : gebruik deze tags alleen voor algemene typen en methoden.
  • <typeparam> *: IntelliSense in Visual Studio geeft de waarde van dit element weer.
  • <typeparamref>

Als u hoekhaken wilt weergeven in de tekst van een opmerking in de documentatie, gebruikt u de HTML-codering van < en >, respectievelijk <> . In het volgende voorbeeld ziet u deze codering.

/// <summary>
/// This property always returns a value &lt; 1.
/// </summary>

Algemene tags

<summary>

<summary>description</summary>

Gebruik de <summary> tag om een type of een typelid te beschrijven. Hiermee <remarks> voegt u aanvullende informatie toe aan een typebeschrijving. Gebruik het cref-kenmerk om documentatiehulpprogramma's zoals DocFX en Sandcastle in te schakelen voor het maken van interne hyperlinks naar documentatiepagina's voor code-elementen. De tekst voor de <summary> tag wordt weergegeven in IntelliSense en in het venster Objectbrowser.

<remarks>

<remarks>
description
</remarks>

Gebruik de <remarks> tag om informatie toe te voegen over een type of een typelid, aangevuld met de informatie die is opgegeven met <summary>. Deze informatie wordt weergegeven in het venster Objectbrowser. Deze tag kan uitgebreidere uitleg bevatten. Mogelijk is CDATA het handiger om secties voor Markdown te gebruiken. Hulpprogramma's zoals docfx verwerken de markdown-tekst in CDATA secties.

Documentleden

<returns>

<returns>description</returns>

Gebruik de <returns> tag in de opmerking voor een methodedeclaratie om de retourwaarde te beschrijven.

<param>

<param name="name">description</param>

• name: De naam van een methodeparameter. Plaats de naam tussen aanhalingstekens ("). De namen voor parameters moeten overeenkomen met de API-handtekening. Als een of meer parameters niet worden gedekt, geeft de compiler een waarschuwing. De compiler geeft ook een waarschuwing uit als de waarde name niet overeenkomt met een formele parameter in de methodedeclaratie.

Gebruik de <param> tag in de opmerking voor een methodedeclaratie om een van de parameters voor de methode te beschrijven. Als u meerdere parameters wilt documenteren, gebruikt u meerdere <param> tags. De tekst voor de <param> tag wordt weergegeven in IntelliSense, de objectbrowser en het webrapport Code Comment.

<paramref>

<paramref name="name"/>

• name: De naam van de parameter waarnaar moet worden verwezen. Plaats de naam tussen aanhalingstekens (").

De <paramref> tag biedt een manier om aan te geven dat een woord in de codeopmerkingen, zoals in een <summary> of <remarks> blok, verwijst naar een parameter. U kunt het XML-bestand verwerken om dit woord op een afzonderlijke manier op te maken, bijvoorbeeld door een vet of cursief lettertype te gebruiken.

<exception>

<exception cref="member">description</exception>

• cref = "member": Een verwijzing naar een uitzondering die beschikbaar is in de huidige compilatieomgeving. De compiler controleert of de opgegeven uitzondering bestaat en wordt omgezet member in de naam van het canonieke element in de uitvoer-XML. member moet worden weergegeven tussen aanhalingstekens (").

Met de <exception> tag kunt u opgeven welke uitzonderingen kunnen worden gegenereerd. Pas deze tag toe op definities voor methoden, eigenschappen, gebeurtenissen en indexeerfuncties.

<value>

<value>property-description</value>

Met <value> de tag kunt u de waarde beschrijven die een eigenschap vertegenwoordigt. Wanneer u een eigenschap toevoegt met behulp van de codewizard in de Ontwikkelomgeving van Visual Studio .NET, wordt er een <summary> tag toegevoegd voor de nieuwe eigenschap. U voegt handmatig een <value> tag toe om de waarde te beschrijven die de eigenschap vertegenwoordigt.

Uitvoer van documentatie opmaken

<para>

<remarks>
    <para>
        This is an introductory paragraph.
    </para>
    <para>
        This paragraph contains more details.
    </para>
</remarks>

Gebruik de <para> tag in een tag, zoals <summary>, <remarks>of <returns>, om structuur toe te voegen aan de tekst. Met de <para> tag wordt een alinea met dubbele afstand gemaakt. Gebruik de <br/> tag als u één regelafstand wilt toevoegen.

Hier volgt een voorbeeld met het verschil tussen <para> en <br/>:

/// <summary>
/// Example using para tags:
/// <para>This is the first paragraph.</para>
/// <para>This is the second paragraph with double spacing.</para>
/// 
/// Example using br tags:
/// First line of text<br/>
/// Second line of text with single spacing<br/>
/// Third line of text
/// </summary>
public void FormattingExample()
{
    // This method demonstrates paragraph and line break formatting
}

<list>

<list type="bullet|number|table">
    <listheader>
        <term>term</term>
        <description>description</description>
    </listheader>
    <item>
        <term>Assembly</term>
        <description>The library or executable built from a compilation.</description>
    </item>
    <item>
        <term>Namespace</term>
        <description>A logical grouping of related types such as classes and interfaces.</description>
    </item>
    <item>
        <term>Class</term>
        <description>A blueprint used to create objects, containing properties and methods.</description>
    </item>
</list>

Gebruik het <listheader> blok om de koprij van een tabel of definitielijst te definiëren.

Bij het definiëren van een tabel:

• Geef een vermelding op voor term in de kop.
• Geef elk item in de lijst op met een <item> blok. Geef voor elke itemvermelding een vermelding op voor description.

Bij het maken van een definitielijst:

• Geef een vermelding op voor term in de kop.
• Geef elk item in de lijst op met een <item> blok. Elk item moet zowel een als termdescriptioneen .

Een lijst of tabel kan zoveel <item> blokken bevatten als nodig is.

<c>

<c>text</c>

Gebruik de <c> tag om tekst in een beschrijving als code te markeren. Gebruik <code> dit om meerdere regels als code aan te geven.

<code>

<code>
    var index = 5;
    index++;
</code>

Gebruik de <code> tag om meerdere regels code aan te geven. Gebruik <c> dit om tekst met één regel binnen een beschrijving als code te markeren.

<example>

<example>
This shows how to increment an integer.
<code>
    var index = 5;
    index++;
</code>
</example>

Gebruik de <example> tag om een voorbeeld te geven van het gebruik van een methode of een ander bibliotheeklid. Een voorbeeld hiervan is het gebruik van de <code> tag.

<b>

<b>text</b>

Gebruik de <b> tag om tekst vet te maken in opmerkingen bij de documentatie. De compiler en Visual Studio valideren deze HTML-opmaaktag. De opgemaakte tekst wordt weergegeven in IntelliSense en gegenereerde documentatie.

<i>

<i>text</i>

Gebruik de <i> tag om tekst cursief te maken in opmerkingen bij de documentatie. De compiler en Visual Studio valideren deze HTML-opmaaktag. De opgemaakte tekst wordt weergegeven in IntelliSense en gegenereerde documentatie.

<u>

<u>text</u>

Gebruik de <u> tag om tekst in opmerkingen bij de documentatie te onderstrepen. De compiler en Visual Studio valideren deze HTML-opmaaktag. De opgemaakte tekst wordt weergegeven in IntelliSense en gegenereerde documentatie.

<br/>

Line one<br/>Line two

Gebruik de <br/> tag om een regeleinde in te voegen in opmerkingen bij documentatie. Gebruik deze tag als u één regelafstand wilt, in plaats van de <para> tag waarmee dubbele alinea's worden gemaakt.

<a>

<a href="https://example.com">Link text</a>

Gebruik de <a> tag om hyperlinks te maken in opmerkingen bij documentatie. Het href kenmerk geeft de URL aan waarnaar moet worden gekoppeld. De compiler en Visual Studio valideren deze HTML-opmaaktag.

Documentatietekst opnieuw gebruiken

<inheritdoc>

<inheritdoc [cref=""] [path=""]/>

XML-opmerkingen overnemen van basisklassen, interfaces en vergelijkbare methoden. Door te gebruiken inheritdoc, elimineert u ongewenste kopiëren en plakken van dubbele XML-opmerkingen en houdt u automatisch XML-opmerkingen gesynchroniseerd. Wanneer u de <inheritdoc> tag aan een type toevoegt, nemen alle leden ook de opmerkingen over.

• cref: Geef het lid op waaruit de documentatie moet worden overgenomen. De overgenomen tags overschrijven niet al gedefinieerde tags op het huidige lid.
• path: De XPath-expressiequery die resulteert in een knooppunt dat wordt weergegeven. Gebruik dit kenmerk om de tags te filteren die moeten worden opgenomen of uitgesloten van de overgenomen documentatie.

Voeg uw XML-opmerkingen toe aan basisklassen of -interfaces en laat de opmerkingen overnemen om klassen te implementeren. Voeg uw XML-opmerkingen toe aan uw synchrone methoden en laat de opmerkingen overnemen naar uw asynchrone versies van dezelfde methoden. Als u de opmerkingen van een specifiek lid wilt kopiëren, gebruikt u het cref kenmerk om het lid op te geven.

<include>

<include file='filename' path='tagpath[@name="id"]' />

• filename: De naam van het XML-bestand met de documentatie. U kunt de bestandsnaam kwalificeren met een pad ten opzichte van het broncodebestand. Plaats enkele aanhalingstekens filename (' ').
• tagpath: Het pad van de tags in filename die leidt tot de tag name. Plaats het pad tussen enkele aanhalingstekens (' ').
• name: De naamaanduiding in de tag die voorafgaat aan de opmerkingen. De name aanduiding heeft een id.
• id: De id voor de tag die voorafgaat aan de opmerkingen. Plaats de id tussen aanhalingstekens (").

Met behulp van de <include> tag kunt u verwijzen naar opmerkingen in een ander bestand waarin de typen en leden in uw broncode worden beschreven. Het opnemen van een extern bestand is een alternatief voor het rechtstreeks in uw broncodebestand plaatsen van documentatieopmerkingen. Door de documentatie in een afzonderlijk bestand te plaatsen, kunt u broncodebeheer afzonderlijk van de broncode toepassen op de documentatie. Eén persoon kan het broncodebestand laten uitchecken en iemand anders kan het documentatiebestand laten uitchecken. De <include> tag maakt gebruik van de XML XPath-syntaxis. Raadpleeg de XPath-documentatie voor manieren om uw <include> gebruik aan te passen.

De volgende broncode gebruikt bijvoorbeeld de <include> tag om opmerkingen op te nemen. Het bestandspad is relatief ten opzichte van de bron.

namespace MyNamespace;

public class MyType
{
    /// <returns>This is the returns text of MyMethod. It comes from triple slash comments.</returns>
    /// <remarks>This is the remarks text of MyMethod. It comes from triple slash comments.</remarks>
    /// <include file="MyAssembly.xml" path="doc/members/member[@name='M:MyNamespace.MyType.MyMethod']/*" />
    public int MyMethod(int p) => p;
}

De XML-bron voor het include-bestand wordt weergegeven in het volgende voorbeeld. Het is gestructureerd op dezelfde wijze als het XML-bestand dat is gegenereerd door de C#-compiler. Het XML-bestand kan tekst bevatten voor meerdere methoden of typen, zolang een XPath-expressie deze kan identificeren.

<?xml version="1.0"?>
<doc>
    <members>
        <member name="M:MyNamespace.MyType.MyMethod">
            <param name="p">This is the description of the parameter p of MyMethod. It comes from the included file.</param>
            <summary>This is the summary of MyMethod. It comes from the included file.</summary>
        </member>
    </members>
</doc>

De XML-uitvoer voor deze methode wordt weergegeven in het volgende voorbeeld:

<member name="M:MyNamespace.MyType.MyMethod(System.Int32)">
    <summary>This is the summary of MyMethod. It comes from the included file.</summary>
    <returns>This is the returns text of MyMethod. It comes from triple slash comments.</returns>
    <remarks>This is the remarks text of MyMethod. It comes from triple slash comments.</remarks>
    <param name="p">This is the description of the parameter p of MyMethod. It comes from the included file.</param>
</member>

Koppelingen en verwijzingen genereren

<see>

<see cref="member"/>
<!-- or -->
<see cref="member">Link text</see>
<!-- or -->
<see href="link">Link Text</see>
<!-- or -->
<see langword="keyword"/>

• cref="member": Een verwijzing naar een lid of veld dat u kunt aanroepen vanuit de huidige compilatieomgeving. De compiler controleert of het opgegeven code-element bestaat en geeft member de naam van het element in de uitvoer-XML door. Plaats lid tussen aanhalingstekens ("). U kunt verschillende koppelingsteksten opgeven voor een cref, met behulp van een afzonderlijke afsluitende tag.
• href="link": Een klikbare koppeling naar een bepaalde URL. Produceert bijvoorbeeld <see href="https://github.com">GitHub</see> een klikbare koppeling met tekst GitHub waarnaar wordt gekoppeld https://github.com. Gebruik href in plaats van cref bij het koppelen aan externe webpagina's, zoals cref is ontworpen voor codeverwijzingen en geen klikbare koppelingen voor externe URL's maakt.
• langword="keyword": Een taaltrefwoord, zoals true of een van de andere geldige trefwoorden.

Met de <see> tag kunt u een koppeling opgeven vanuit tekst. Gebruik <seealso> dit om aan te geven dat tekst in een sectie Zie ook moet worden geplaatst. Gebruik het kenmerk Cref om interne hyperlinks naar documentatiepagina's voor code-elementen te maken. Neem de typeparameters op om een verwijzing naar een algemeen type of methode op te geven, zoals cref="IDictionary{T, U}". href Is ook een geldig kenmerk dat als hyperlink fungeert.

Hier volgt een voorbeeld met het verschil tussen cref en href bij het verwijzen naar externe URL's:

/// <summary>
/// This method demonstrates URL linking:
/// <see cref="https://learn.microsoft.com/dotnet/csharp"/> (won't create clickable link)
/// <see href="https://learn.microsoft.com/dotnet/csharp">C# documentation</see> (creates clickable link)
/// </summary>
public void UrlLinkingExample()
{
    // This method demonstrates the difference between cref and href for URLs
}

<seealso>

<seealso cref="member"/>
<!-- or -->
<seealso href="link">Link Text</seealso>

• cref="member": Een verwijzing naar een lid of veld dat u kunt aanroepen vanuit de huidige compilatieomgeving. De compiler controleert of het opgegeven code-element bestaat en geeft member de naam van het element in de uitvoer-XML door. member moet worden weergegeven tussen aanhalingstekens (").
• href="link": Een klikbare koppeling naar een bepaalde URL. Produceert bijvoorbeeld <seealso href="https://github.com">GitHub</seealso> een klikbare koppeling met tekst GitHub waarnaar wordt gekoppeld https://github.com.

<seealso> Met de tag kunt u de tekst opgeven die u mogelijk wilt weergeven in een sectie Zie ook. Hiermee <see> geeft u een koppeling op vanuit tekst. U kunt de seealso tag niet nesten in de summary tag.

cref-kenmerk

Het cref kenmerk in een XML-documentatietag betekent 'codereferentie'. Hiermee geeft u op dat de binnenste tekst van de tag een code-element is, zoals een type, methode of eigenschap. Documentatiehulpprogramma's zoals DocFX en Sandcastle gebruiken de cref kenmerken om automatisch hyperlinks te genereren naar de pagina waar het type of lid wordt gedocumenteerd.

href-kenmerk

Het href kenmerk betekent een verwijzing naar een webpagina. U kunt deze gebruiken om rechtstreeks naar onlinedocumentatie over uw API of bibliotheek te verwijzen. Wanneer u een koppeling naar externe URL's in uw documentatieopmerkingen moet maken, gebruikt u href in plaats van cref om ervoor te zorgen dat de koppelingen klikbaar zijn in IntelliSense tooltips en gegenereerde documentatie.

Algemene typen en methoden

<typeparam>

<typeparam name="TResult">The type returned from this method</typeparam>

• TResult: De naam van de typeparameter. Plaats de naam tussen aanhalingstekens (").

De <typeparam> tag moet worden gebruikt in de opmerking voor een algemeen type of methodedeclaratie om een typeparameter te beschrijven. Voeg een tag toe voor elke typeparameter van het algemene type of de methode. De tekst voor de <typeparam> tag wordt weergegeven in IntelliSense.

<typeparamref>

<typeparamref name="TKey"/>

• TKey: De naam van de typeparameter. Plaats de naam tussen aanhalingstekens (").

Gebruik deze tag om consumenten van het documentatiebestand in staat te stellen het woord op een duidelijke manier op te maken, bijvoorbeeld cursief.

Door de gebruiker gedefinieerde tags

Alle tags die in dit artikel worden beschreven, vertegenwoordigen de tags die worden herkend door de C#-compiler. Een gebruiker is echter vrij om hun eigen tags te definiëren. Hulpprogramma's zoals Sandcastle bieden ondersteuning voor extra tags, zoals <event> en <note>, en bieden zelfs ondersteuning voor het documenteren van naamruimten. 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.