Delen via

Aanbevolen XML-tags voor opmerkingen bij C#-documentatie

  • Artikel

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.

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. In alle gevallen moet u voldoen aan deze aanbevelingen:

  • In het belang van consistentie moeten alle openbaar zichtbare typen en hun openbare leden worden gedocumenteerd.
  • Privéleden kunnen ook worden gedocumenteerd met XML-opmerkingen. Het toont echter de interne (mogelijk vertrouwelijke) werking van uw bibliotheek.
  • Minimaal moeten typen en hun leden een <summary> tag hebben.
  • De documentatietekst moet worden geschreven 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 wordt gebruikt om parameters te beschrijven. Als deze wordt 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.
    • Het cref kenmerk kan worden gekoppeld aan elke 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.
    • De <summary> tag wordt gebruikt door IntelliSense in Visual Studio 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.

Notitie

Opmerkingen bij documentatie kunnen niet worden toegepast op een naamruimte.

Als u hoekhaken wilt weergeven in de tekst van een opmerking in de documentatie, gebruikt u de HTML-codering van < en >, respectievelijk &lt; &gt; . Deze codering wordt weergegeven in het volgende voorbeeld.

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

Algemene tags

<samenvatting>

<summary>description</summary>

De <summary> tag moet worden gebruikt om een type of een typelid te beschrijven. Gebruik <opmerkingen> om aanvullende informatie toe te voegen 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.

<Opmerkingen>

<remarks>
description
</remarks>

De <remarks> tag wordt gebruikt voor het toevoegen van informatie over een type of een typelid, aangevuld met de informatie die is opgegeven met <een samenvatting>. 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

<Retourneert>

<returns>description</returns>

De <returns> tag moet worden gebruikt 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.

De <param> tag moet worden gebruikt 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 codecommentaar.

<paramref>

<paramref name="name"/>
  • name: De naam van de parameter waarnaar moet worden verwezen. Plaats de naam tussen aanhalingstekens (").

Met <paramref> de tag kunt u aangeven dat een woord in de codeopmerkingen, bijvoorbeeld in een <summary> of <remarks> blok, verwijst naar een parameter. Het XML-bestand kan op een duidelijke manier worden verwerkt om dit woord op te maken, zoals met een vet of cursief lettertype.

<uitzondering>

<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. Deze tag kan worden toegepast 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 via de codewizard in de Ontwikkelomgeving van Visual Studio .NET, wordt er een <samenvattingstag> 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>

De <para> tag is bedoeld voor gebruik in een tag, zoals <samenvatting>, <opmerkingen of <retourneert>>, en u kunt structuur toevoegen aan de tekst. Met de <para> tag wordt een alinea met dubbele afstand gemaakt. Gebruik de <br/> tag als u één regelafstand wilt toevoegen.

<lijst>

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

Het <listheader> blok wordt gebruikt om de koprij van een tabel- of definitielijst te definiëren.

Bij het definiëren van een tabel:

  • U hoeft alleen een vermelding term op te geven in de kop.
  • Elk item in de lijst wordt opgegeven met een <item> blok. Voor elk itemitem hoeft u alleen een vermelding op te geven voor description.

Bij het maken van een definitielijst:

  • U moet een vermelding opgeven voor term de kop.
  • Elk item in de lijst wordt opgegeven met een <item> blok. Elk item moet zowel een als term descriptioneen .

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

<c>

<c>text</c>

Met de <c> tag kunt u aangeven dat tekst in een beschrijving moet worden gemarkeerd als code. Gebruik <code> om meerdere regels als code aan te geven.

<code>

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

De <code> tag wordt gebruikt om meerdere regels code aan te geven. Gebruik <c> om aan te geven dat tekst met één regel binnen een beschrijving moet worden gemarkeerd als code.

<voorbeeld>

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

Met de <example> tag kunt u een voorbeeld opgeven van het gebruik van een methode of een ander bibliotheeklid. Een voorbeeld hiervan is het gebruik van de codetag>.<

Documentatietekst opnieuw gebruiken

<inheritdoc>

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

XML-opmerkingen overnemen van basisklassen, interfaces en vergelijkbare methoden. Het gebruik inheritdoc elimineert ongewenste kopieer- en plakbewerkingen van dubbele XML-opmerkingen en zorgt ervoor dat XML-opmerkingen automatisch worden 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. Al gedefinieerde tags voor het huidige lid worden niet overschreven door de overgenomen tags.
  • path: De XPath-expressiequery die resulteert in een knooppunt dat wordt weergegeven. U kunt dit kenmerk gebruiken om de tags op te nemen of uit te sluiten 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.

<bevatten>

<include file='filename' path='tagpath[@name="id"]' />
  • filename: De naam van het XML-bestand met de documentatie. De bestandsnaam kan worden gekwalificeerd 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; name heeft een id.
  • id: De id voor de tag die voorafgaat aan de opmerkingen. Plaats de id tussen aanhalingstekens (").

Met <include> de 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>

Tip

Het .NET Runtime-team gebruikt de tag uitgebreid in de <include> documentatie. U kunt veel voorbeelden bekijken door in de dotnet/runtime opslagplaats te zoeken.

<zien>

<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 beschikbaar is om te worden aangeroepen 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 koppelingstekst 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.
  • 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> 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. U neemt 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.

<seealso>

<seealso cref="member"/>
<!-- or -->
<seealso href="link">Link Text</seealso>
  • cref="member": Een verwijzing naar een lid of veld dat beschikbaar is om te worden aangeroepen 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. Gebruik <zie> om een koppeling op te geven 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.

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 <gebeurtenissen> en< notities>, en bieden zelfs ondersteuning voor documentnaamruimten. 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.