Share via

Rekommenderade XML-taggar för C#-dokumentationskommentar

  • Artikel

Kommentarer i C#-dokumentationen använder XML-element för att definiera strukturen i utdatadokumentationen. En konsekvens av den här funktionen är att du kan lägga till giltig XML i dina dokumentationskommentar. C#-kompilatorn kopierar dessa element till XML-utdatafilen. Även om du kan använda valfri giltig XML i dina kommentarer (inklusive ett giltigt HTML-element), rekommenderas dokumentkod av många skäl.

Följande är några rekommendationer, allmänna användningsfall och saker som du bör känna till när du använder XML-dokumentationstaggar i C#-koden. Du kan lägga till taggar i dina dokumentationskommenter, men den här artikeln beskriver de rekommenderade taggarna för de vanligaste språkkonstruktionerna. I samtliga fall bör du följa dessa rekommendationer:

  • För konsekvensens skull bör alla offentligt synliga typer och deras offentliga medlemmar dokumenteras.
  • Privata medlemmar kan också dokumenteras med XML-kommentarer. Den exponerar dock bibliotekets inre (potentiellt konfidentiella) funktioner.
  • Som minst ska typer och deras medlemmar ha en <summary> tagg.
  • Dokumentationstexten ska skrivas med fullständiga meningar som slutar med fullständiga stopp.
  • Partiella klasser stöds fullt ut och dokumentationsinformation sammanfogas till en enda post för varje typ.

XML-dokumentationen börjar med ///. När du skapar ett nytt projekt lägger mallarna in några startrader /// åt dig. Bearbetningen av dessa kommentarer har vissa begränsningar:

  • Dokumentationen måste vara välformulerad XML. Om XML-koden inte är väl utformad genererar kompilatorn en varning. Dokumentationsfilen innehåller en kommentar som anger att ett fel påträffades.
  • Några av de rekommenderade taggarna har särskilda betydelser:
    • Taggen <param> används för att beskriva parametrar. Om den används verifierar kompilatorn att parametern finns och att alla parametrar beskrivs i dokumentationen. Om verifieringen misslyckas utfärdar kompilatorn en varning.
    • Attributet cref kan kopplas till valfri tagg för att referera till ett kodelement. Kompilatorn verifierar att det här kodelementet finns. Om verifieringen misslyckas utfärdar kompilatorn en varning. Kompilatorn respekterar alla using instruktioner när den söker efter en typ som beskrivs i attributet cref .
    • Taggen <summary> används av IntelliSense i Visual Studio för att visa ytterligare information om en typ eller medlem.

      Kommentar

      XML-filen innehåller inte fullständig information om typen och medlemmarna (till exempel innehåller den ingen typinformation). Om du vill få fullständig information om en typ eller medlem använder du dokumentationsfilen tillsammans med reflektion över den faktiska typen eller medlemmen.

  • Utvecklare kan skapa en egen uppsättning taggar. Kompilatorn kopierar dessa till utdatafilen.

Vissa av de rekommenderade taggarna kan användas på valfritt språkelement. Andra har mer specialiserad användning. Slutligen används några av taggarna för att formatera text i dokumentationen. I den här artikeln beskrivs de rekommenderade taggarna som ordnas efter deras användning.

Kompilatorn verifierar syntaxen för elementen följt av en enda * i följande lista. Visual Studio tillhandahåller IntelliSense för taggarna som verifierats av kompilatorn och alla taggar följt av ** i följande lista. Förutom taggarna som anges här validerar kompilatorn och Visual Studio taggarna <b>, <i>, <u>, <br/>och <a> . Kompilatorn validerar <tt>också , som är inaktuell HTML.

Kommentar

Det går inte att tillämpa dokumentationskommentare på ett namnområde.

Om du vill att vinkelparenteser ska visas i texten i en dokumentationskommentare använder du HTML-kodningen för < och >, som är &lt; respektive &gt; . Den här kodningen visas i följande exempel.

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

Allmänna taggar

<Sammanfattning>

<summary>description</summary>

Taggen <summary> ska användas för att beskriva en typ eller en typmedlem. Använd <kommentarer> för att lägga till kompletterande information i en typbeskrivning. Använd cref-attributet för att aktivera dokumentationsverktyg som DocFX och Sandcastle för att skapa interna hyperlänkar till dokumentationssidor för kodelement. Texten för taggen <summary> visas i IntelliSense och i fönstret Object Browser.

<Anmärkningar>

<remarks>
description
</remarks>

Taggen <remarks> används för att lägga till information om en typ eller en typmedlem, vilket kompletterar den information som anges med <sammanfattning>. Den här informationen visas i fönstret Objektwebbläsare. Den här taggen kan innehålla mer långa förklaringar. Du kanske tycker att det är enklare att skriva med hjälp av CDATA avsnitt för markdown. Verktyg som docfx bearbetar markdown-texten i CDATA avsnitt.

Dokumentmedlemmar

<Returnerar>

<returns>description</returns>

Taggen <returns> ska användas i kommentaren för en metoddeklaration för att beskriva returvärdet.

<Param>

<param name="name">description</param>
  • name: Namnet på en metodparameter. Omslut namnet inom dubbla citattecken (" "). Namnen på parametrarna måste matcha API-signaturen. Om en eller flera parametrar inte omfattas utfärdar kompilatorn en varning. Kompilatorn utfärdar också en varning om värdet name för inte matchar en formell parameter i metoddeklarationen.

Taggen <param> ska användas i kommentaren för en metoddeklaration för att beskriva en av parametrarna för metoden. Om du vill dokumentera flera parametrar använder du flera <param> taggar. Texten för taggen <param> visas i IntelliSense, Object Browser och kodkommentarwebbrapporten.

<paramref>

<paramref name="name"/>
  • name: Namnet på parametern som ska refereras till. Omslut namnet inom dubbla citattecken (" ").

Taggen <paramref> ger dig ett sätt att ange att ett ord i kodkommentarna, till exempel i ett <summary> eller <remarks> ett block, refererar till en parameter. XML-filen kan bearbetas för att formatera det här ordet på något distinkt sätt, till exempel med ett fetstilt eller kursivt teckensnitt.

<Undantag>

<exception cref="member">description</exception>
  • cref = "member": En referens till ett undantag som är tillgängligt från den aktuella kompileringsmiljön. Kompilatorn kontrollerar att det angivna undantaget finns och översätter member till det kanoniska elementnamnet i xml-utdata. member måste visas inom dubbla citattecken (" ").

Med <exception> taggen kan du ange vilka undantag som kan genereras. Den här taggen kan användas för definitioner för metoder, egenskaper, händelser och indexerare.

<värde>

<value>property-description</value>

Med <value> taggen kan du beskriva värdet som en egenskap representerar. När du lägger till en egenskap via kodguiden i Visual Studio .NET-utvecklingsmiljön lägger den till en <sammanfattningstagg> för den nya egenskapen. Du lägger till en <value> tagg manuellt för att beskriva värdet som egenskapen representerar.

Formatera dokumentationsutdata

<Para>

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

Taggen <para> är avsedd att användas i en tagg, till exempel <sammanfattning>, <kommentarer> eller <returer>, och gör att du kan lägga till struktur i texten. Taggen <para> skapar ett stycke med dubbelt blanksteg. Använd taggen <br/> om du vill ha ett stycke med ett enda blanksteg.

<lista>

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

Blocket <listheader> används för att definiera rubrikraden i en tabell eller definitionslista. När du definierar en tabell behöver du bara ange en post för term i rubriken. Varje objekt i listan anges med ett <item> block. När du skapar en definitionslista måste du ange både term och description. För en tabell, punktlista eller numrerad lista behöver du dock bara ange en post för description. En lista eller tabell kan ha så många <item> block som behövs.

<C>

<c>text</c>

Taggen <c> ger dig ett sätt att ange att text i en beskrivning ska markeras som kod. Använd <kod> för att ange flera rader som kod.

<kod>

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

Taggen <code> används för att ange flera kodrader. Använd <c> för att ange att enkelradstext i en beskrivning ska markeras som kod.

<Exempel>

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

Med <example> taggen kan du ange ett exempel på hur du använder en metod eller annan biblioteksmedlem. Ett exempel handlar ofta om att använda kodtaggen><.

Återanvänd dokumentationstext

<inheritdoc>

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

Ärv XML-kommentarer från basklasser, gränssnitt och liknande metoder. Med hjälp av inheritdoc elimineras oönskad kopiering och klistra in duplicerade XML-kommentarer och håller automatiskt XML-kommentarer synkroniserade. Observera att när du lägger till taggen <inheritdoc> i en typ ärver även alla medlemmar kommentarerna.

  • cref: Ange den medlem som ska ärva dokumentationen från. Redan definierade taggar på den aktuella medlemmen åsidosätts inte av de ärvda.
  • path: Den XPath-uttrycksfråga som resulterar i en noduppsättning som ska visas. Du kan använda det här attributet för att filtrera taggarna som ska inkluderas eller undantas från den ärvda dokumentationen.

Lägg till dina XML-kommentarer i basklasser eller gränssnitt och låt inheritdoc kopiera kommentarerna till att implementera klasser. Lägg till DINA XML-kommentarer i dina synkrona metoder och låt inheritdoc kopiera kommentarerna till dina asynkrona versioner av samma metoder. Om du vill kopiera kommentarerna från en viss medlem använder cref du attributet för att ange medlemmen.

<Inkluderar>

<include file='filename' path='tagpath[@name="id"]' />
  • filename: Namnet på XML-filen som innehåller dokumentationen. Filnamnet kan kvalificeras med en sökväg i förhållande till källkodsfilen. Omsluta filename med enkla citattecken (' ').
  • tagpath: Sökvägen till taggarna i filename som leder till taggen name. Omslut sökvägen inom enkla citattecken (' ').
  • name: Namnspecificeraren i taggen som föregår kommentarerna. name kommer att ha en id.
  • id: ID:t för taggen som föregår kommentarerna. OmslutA ID:t med dubbla citattecken (" ").

Med <include> taggen kan du referera till kommentarer i en annan fil som beskriver typerna och medlemmarna i källkoden. Att inkludera en extern fil är ett alternativ till att placera dokumentationskommentar direkt i källkodsfilen. Genom att placera dokumentationen i en separat fil kan du använda källkontroll i dokumentationen separat från källkoden. En person kan checka ut källkodsfilen och någon annan kan checka ut dokumentationsfilen. Taggen <include> använder XML XPath-syntaxen. I XPath-dokumentationen finns olika sätt att anpassa din <include> användning.

Följande källkod använder till exempel taggen <include> för att inkludera kommentarer. Filsökvägen är relativ till källan.

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;
}

XML-källan för inkluderingsfilen visas i följande exempel. Den är strukturerad på samma sätt som XML-filen som genereras av C#-kompilatorn. XML-filen kan innehålla text för flera metoder eller typer, så länge ett XPath-uttryck kan identifiera dem.

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

XML-utdata för den här metoden visas i följande exempel:

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

Dricks

.NET Runtime-teamet använder taggen <include> i stor utsträckning i sin dokumentation. Du kan se många exempel genom att söka på lagringsplatsendotnet/runtime.

<Se>

<see cref="member"/>
<!-- or -->
<see cref="member">Link text</see>
<!-- or -->
<see href="link">Link Text</see>
<!-- or -->
<see langword="keyword"/>
  • cref="member": En referens till en medlem eller ett fält som är tillgängligt för att anropas från den aktuella kompileringsmiljön. Kompilatorn kontrollerar att det angivna kodelementet finns och skickar member till elementnamnet i xml-utdata. Placera medlemmen inom dubbla citattecken (" "). Du kan ange en annan länktext för en "cref" med hjälp av en separat avslutande tagg.
  • href="link": En klickbar länk till en viss URL. Skapar till exempel <see href="https://github.com">GitHub</see> en klickbar länk med text GitHub som länkar till https://github.com.
  • langword="keyword": Ett språknyckelord, till exempel true eller något av de andra giltiga nyckelorden.

Med <see> taggen kan du ange en länk inifrån text. Använd <seealso för> att ange att texten ska placeras i avsnittet Se även. Använd cref-attributet för att skapa interna hyperlänkar till dokumentationssidor för kodelement. Du inkluderar typparametrarna för att ange en referens till en allmän typ eller metod, till exempel cref="IDictionary{T, U}". href Är också ett giltigt attribut som fungerar som en hyperlänk.

<seealso>

<seealso cref="member"/>
<!-- or -->
<seealso href="link">Link Text</seealso>
  • cref="member": En referens till en medlem eller ett fält som är tillgängligt för att anropas från den aktuella kompileringsmiljön. Kompilatorn kontrollerar att det angivna kodelementet finns och skickar member till elementnamnet i xml-utdata. member måste visas inom dubbla citattecken (" ").
  • href="link": En klickbar länk till en viss URL. Skapar till exempel <seealso href="https://github.com">GitHub</seealso> en klickbar länk med text GitHub som länkar till https://github.com.

Med <seealso> taggen kan du ange den text som du kanske vill ska visas i avsnittet Se även . Använd <se> om du vill ange en länk inifrån text. Du kan inte kapsla taggen seealso i taggen summary .

cref-attribut

Attributet cref i en XML-dokumentationstagg betyder "kodreferens". Den anger att den inre texten i taggen är ett kodelement, till exempel en typ, metod eller egenskap. Dokumentationsverktyg som DocFX och Sandcastle använder attributen cref för att automatiskt generera hyperlänkar till sidan där typen eller medlemmen dokumenteras.

href-attribut

Attributet href innebär en referens till en webbsida. Du kan använda den för att direkt referera till onlinedokumentation om ditt API eller bibliotek.

Allmänna typer och metoder

<typeparam>

<typeparam name="TResult">The type returned from this method</typeparam>
  • TResult: Namnet på typparametern. Omslut namnet inom dubbla citattecken (" ").

Taggen <typeparam> ska användas i kommentaren för en allmän typ eller metoddeklaration för att beskriva en typparameter. Lägg till en tagg för varje typparameter av den generiska typen eller metoden. Texten för taggen <typeparam> visas i IntelliSense.

<typeparamref>

<typeparamref name="TKey"/>
  • TKey: Namnet på typparametern. Omslut namnet inom dubbla citattecken (" ").

Använd den här taggen för att göra det möjligt för användare av dokumentationsfilen att formatera ordet på något distinkt sätt, till exempel i kursiv stil.

Användardefinierade taggar

Alla taggar som beskrivs ovan representerar de taggar som identifieras av C#-kompilatorn. En användare kan dock definiera sina egna taggar. Verktyg som Sandcastle ger stöd för extra taggar som <händelse> och anteckning>, och stöder till och <med dokumentnamnområden. Anpassade eller interna verktyg för dokumentationsgenerering kan också användas med standardtaggar, och flera utdataformat från HTML till PDF kan stödjas.