Sdílet prostřednictvím

Doporučené značky XML pro komentáře dokumentace jazyka C#

Komentáře dokumentace jazyka C# používají elementy XML k definování struktury výstupní dokumentace. Jedním z důsledků této funkce je, že do komentářů v dokumentaci můžete přidat libovolný platný kód XML. Kompilátor jazyka C# zkopíruje tyto prvky do výstupního souboru XML. I když můžete v komentářích použít libovolný platný KÓD XML (včetně libovolného platného elementu HTML), doporučuje se z mnoha důvodů dokumentovat kód.

Referenční dokumentace jazyka C# dokumentuje naposledy vydané verze jazyka C#. Obsahuje také počáteční dokumentaci k funkcím ve verzi Public Preview pro nadcházející jazykovou verzi.

Dokumentace identifikuje všechny funkce, které byly poprvé představeny v posledních třech verzích jazyka nebo v aktuálních verzích Public Preview.

Návod

Informace o tom, kdy byla funkce poprvé představena v jazyce C#, najdete v článku o historii verzí jazyka C#.

Následuje několik doporučení, scénáře obecného použití a věci, které byste měli vědět při použití značek dokumentace XML v kódu jazyka C#. I když můžete do komentářů k dokumentaci vložit jakékoli značky, tento článek popisuje doporučené značky pro nejběžnější jazykové konstrukce. Dodržujte tato doporučení:

  • Kvůli konzistenci zdokumentujte všechny veřejně viditelné typy a jejich veřejné členy.
  • Soukromé členy můžete dokumentovat také pomocí komentářů XML. Tento přístup ale zpřístupňuje vnitřní (potenciálně důvěrné) práce vaší knihovny.
  • Minimální typ a jejich členové by měly mít <summary> značku.
  • Napište text dokumentace pomocí celých vět, které končí úplnými zarážkami.
  • Částečné třídy jsou plně podporované a informace o dokumentaci jsou zřetězeny do jedné položky pro každý typ. Pokud obě deklarace částečného členu mají komentáře k dokumentaci, komentáře k implementační deklaraci jsou zapsány do výstupního XML.

Dokumentace XML začíná na ///. Když vytvoříte nový projekt, šablony za vás vloží několik počátečních /// řádků. Zpracování těchto komentářů má určitá omezení:

  • Dokumentace musí být ve správném formátu XML. Pokud xml není správně vytvořený, kompilátor vygeneruje upozornění. Soubor dokumentace obsahuje komentář s informací, že došlo k chybě.
  • Některé z doporučených značek mají zvláštní význam:
    • Značka <param> popisuje parametry. Pokud použijete tuto značku, kompilátor ověří, že parametr existuje a že všechny parametry jsou popsané v dokumentaci. Pokud se ověření nezdaří, kompilátor vydá upozornění.
    • cref Připojte atribut k jakékoli značce, která odkazuje na prvek kódu. Kompilátor ověří, že tento prvek kódu existuje. Pokud se ověření nezdaří, kompilátor vydá upozornění. Kompilátor respektuje všechny using direktivy, když hledá typ popsaný v atributu cref .
    • IntelliSense v sadě Visual Studio používá <summary> značku k zobrazení dalších informací o typu nebo členu.

      Poznámka:

      Soubor XML neposkytuje úplné informace o typu a členech (například neobsahuje žádné informace o typu). Pokud chcete získat úplné informace o typu nebo členu, použijte soubor dokumentace společně s reflexí skutečného typu nebo člena.

  • Vývojáři mohou vytvářet vlastní sadu značek. Kompilátor tyto značky zkopíruje do výstupního souboru.

Některé z doporučených značek lze použít pro libovolný prvek jazyka. Jiné mají specializovanější využití. Nakonec se některé značky používají k formátování textu v dokumentaci. Tento článek popisuje doporučené značky uspořádané podle jejich použití.

Kompilátor ověří syntaxi prvků následovaných jedním * v následujícím seznamu. Visual Studio poskytuje IntelliSense pro značky ověřené kompilátorem a všechny značky následované ** v následujícím seznamu. Kromě značek uvedených zde kompilátor a Visual Studio ověřují <b>, <i>, <u>, <br/>a <a> značky. Kompilátor také ověří <tt>, což je zastaralé HTML.

Poznámka:

Značky HTML, jako <br/> jsou užitečné pro formátování v komentářích dokumentace. Značka <br/> vytváří konce řádků, zatímco jiné značky HTML poskytují formátování textu. Tyto značky fungují v popisech IntelliSense a vygenerované dokumentaci.

Poznámka:

Komentáře k dokumentaci nemůžete použít u oboru názvů.

Pokud chcete, aby se v textu komentáře dokumentace zobrazovaly úhlové závorky, použijte kódování < HTML, >které je &lt; a &gt; v uvedeném pořadí. Následující příklad ukazuje toto kódování.

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

Obecné značky

<summary>

<summary>description</summary>

<summary> Značka slouží k popisu typu nebo člena typu. Slouží <remarks> k přidání doplňkových informací do popisu typu. Pomocí atributu cref povolte nástroje dokumentace, jako jsou DocFX a Sandcastle, k vytvoření interních hypertextových odkazů na stránky dokumentace pro prvky kódu. Text značky <summary> se zobrazí v IntelliSense a v okně Prohlížeče objektů.

<remarks>

<remarks>
description
</remarks>

<remarks> Značka slouží k přidání informací o typu nebo členu typu, doplnění informací zadaných <summary>pomocí . Tyto informace se zobrazí v okně Prohlížeče objektů. Tato značka může obsahovat delší vysvětlení. Možná zjistíte, že použití CDATA oddílů pro Markdown usnadňuje psaní. Nástroje, jako je docfx , zpracovávají text markdownu v CDATA oddílech.

Členové dokumentu

<returns>

<returns>description</returns>

<returns> K popisu návratové hodnoty použijte značku v komentáři pro deklaraci metody.

<param>

<param name="name">description</param>
  • name: Název parametru metody. Uzavřete název do uvozovek ("). Názvy parametrů musí odpovídat podpisu rozhraní API. Pokud nejsou zahrnuty některé parametry, kompilátor vydá upozornění. Kompilátor také vydá upozornění, pokud hodnota name neodpovídá formálnímu parametru v deklaraci metody.

<param> K popisu jednoho z parametrů metody použijte značku v komentáři pro deklaraci metody. Pokud chcete dokumentovat více parametrů, použijte více <param> značek. Text značky <param> se zobrazí v IntelliSense, prohlížeči objektů a webové sestavě komentáře kódu.

<paramref>

<paramref name="name"/>
  • name: Název parametru, na který se má odkazovat. Uzavřete název do uvozovek (").

Značka <paramref> poskytuje způsob, jak označit, že slovo v komentářích kódu, například v <summary><remarks> bloku, odkazuje na parametr. Soubor XML můžete zpracovat a naformátovat toto slovo odlišným způsobem, například pomocí tučného písma nebo kurzívy.

<exception>

<exception cref="member">description</exception>
  • cref = "member": Odkaz na výjimku, která je k dispozici v aktuálním prostředí kompilace. Kompilátor zkontroluje, zda daná výjimka existuje, a přeloží member na název kanonického elementu ve výstupním XML. member musí být uveden v uvozovkách (").

Značka <exception> umožňuje určit, které výjimky je možné vyvolat. Tuto značku použijte u definic pro metody, vlastnosti, události a indexery.

<value>

<value>property-description</value>

Značka <value> umožňuje popsat hodnotu, kterou vlastnost představuje. Když přidáte vlastnost pomocí průvodce kódem ve vývojovém prostředí sady Visual Studio .NET, přidá <summary> značku pro novou vlastnost. Ručně přidáte <value> značku, která popisuje hodnotu, kterou vlastnost představuje.

Formátování výstupu dokumentace

<para>

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

Pomocí značky <para> uvnitř značky, například <summary>, <remarks>nebo <returns>, přidejte do textu strukturu. Značka <para> vytvoří odstavec s dvojitým řádkem. <br/> Značku použijte, pokud chcete použít jeden mezerník odstavce.

Tady je příklad znázorňující rozdíl mezi <para> a <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>

<listheader> Pomocí bloku definujte řádek záhlaví tabulky nebo seznamu definic.

Při definování tabulky:

  • Zadejte položku pro term nadpis.
  • Zadejte každou položku v seznamu blokem <item> . Pro každou itempoložku zadejte položku pro description.

Při vytváření seznamu definic:

  • Zadejte položku pro term nadpis.
  • Zadejte každou položku v seznamu blokem <item> . Každý item musí obsahovat jak a termdescription , tak .

Seznam nebo tabulka můžou mít libovolný počet <item> bloků.

<c>

<c>text</c>

<c> Značka slouží k označení textu v popisu jako kódu. Slouží <code> k označení více řádků jako kódu.

<code>

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

<code> Značka slouží k označení více řádků kódu. Slouží <c> k označení jednořádkového textu v popisu jako kódu.

<example>

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

Pomocí značky <example> uveďte příklad použití metody nebo jiného člena knihovny. Příkladem často bývá použití <code> značky.

<b>

<b>text</b>

Pomocí značky <b> můžete v komentářích dokumentace nastavit text tučným písmem. Kompilátor a Visual Studio ověřují tuto značku formátování HTML. Formátovaný text se zobrazí v IntelliSense a vygenerovaná dokumentace.

<i>

<i>text</i>

<i> Značka slouží k vytvoření textové kurzívy v komentářích dokumentace. Kompilátor a Visual Studio ověřují tuto značku formátování HTML. Formátovaný text se zobrazí v IntelliSense a vygenerovaná dokumentace.

<u>

<u>text</u>

<u> Značka slouží k podtržení textu v komentářích dokumentace. Kompilátor a Visual Studio ověřují tuto značku formátování HTML. Formátovaný text se zobrazí v IntelliSense a vygenerovaná dokumentace.

<br/>

Line one<br/>Line two

<br/> Značka slouží k vložení konce řádku do komentářů dokumentace. Tuto značku použijte, pokud chcete, aby byl odstavec s jedním řádkem na rozdíl od <para> značky, která vytváří dvojité mezery mezi odstavci.

<a>

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

<a> Pomocí značky můžete vytvářet hypertextové odkazy v komentářích dokumentace. Atribut href určuje adresu URL, na které se má odkazovat. Kompilátor a Visual Studio ověřují tuto značku formátování HTML.

Poznámka:

Kompilátor také ověří <tt> značku, která je zastaralá ve formátu HTML. Místo toho použijte značku <c> pro formátování vloženého kódu.

Opakované použití textu dokumentace

<inheritdoc>

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

Dědí komentáře XML ze základních tříd, rozhraní a podobných metod. Pomocí , inheritdoceliminujete nežádoucí kopírování a vkládání duplicitních komentářů XML a automaticky udržovat komentáře XML synchronizované. Když značku přidáte <inheritdoc> k typu, všichni členové také zdědí komentáře.

  • cref: Zadejte člena, ze které má být zděděna dokumentace. Zděděné značky nepřepíší již definované značky u aktuálního člena.
  • path: Dotaz výrazu XPath, který má za následek zobrazení sady uzlů. Tento atribut použijte k filtrování značek, které mají být zahrnuty nebo vyloučeny z zděděné dokumentace.

Poznámka:

Visual Studio automaticky dědí dokumentaci XML pro nezdokumentované členy, kteří přepisují nebo implementují zdokumentované členy. Tato funkce zobrazuje zděděnou dokumentaci v IntelliSense a rychlých informacích bez nutnosti značky <inheritdoc> . Tato automatická dědičnost se ale vztahuje pouze v integrovaném vývojovém prostředí sady Visual Studio a nemá vliv na soubor dokumentace XML vygenerovaný kompilátorem.

Pro veřejná rozhraní API v knihovnách, které distribuujete, explicitně použijte <inheritdoc> značku nebo poskytněte úplnou dokumentaci, abyste zajistili, že vygenerovaný soubor dokumentace XML obsahuje všechny potřebné informace pro uživatele vaší knihovny.

Přidejte komentáře XML do základních tříd nebo rozhraní a nechte zdědit komentáře do implementace tříd. Přidejte komentáře XML do synchronních metod a nechte zdědit komentáře do asynchronních verzí stejných metod. Pokud chcete kopírovat komentáře od určitého člena, použijte cref atribut k určení člena.

<include>

<include file='filename' path='tagpath[@name="id"]' />
  • filename: Název souboru XML obsahujícího dokumentaci. Název souboru můžete kvalifikovat cestou vzhledem k souboru zdrojového kódu. Uzavřete filename do jednoduchých uvozovek (' ').
  • tagpath: Cesta značek, filename které vedou ke značce name. Uzavřete cestu do jednoduchých uvozovek (' ').
  • name: Specifikátor názvu ve značce, která předchází komentářům. Specifikátor name má hodnotu id.
  • id: ID značky, která předchází komentářům. Uzavřete ID do uvozovek (").

Pomocí značky <include> můžete odkazovat na komentáře v jiném souboru, který popisuje typy a členy ve zdrojovém kódu. Zahrnutí externího souboru je alternativou k umístění komentářů dokumentace přímo do souboru zdrojového kódu. Umístěním dokumentace do samostatného souboru můžete použít správu zdrojového kódu v dokumentaci odděleně od zdrojového kódu. Jedna osoba může mít rezervovaný soubor zdrojového kódu a někdo jiný může mít rezervovaný soubor dokumentace. Značka <include> používá syntaxi XML XPath. Způsoby přizpůsobení <include> použití najdete v dokumentaci k XPathu.

Například následující zdrojový kód používá <include> značku k zahrnutí poznámek. Cesta k souboru je relativní vzhledem ke zdroji.

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

Zdroj XML pro zahrnutý soubor je uveden v následující ukázce. Je strukturovaná stejně jako soubor XML generovaný kompilátorem jazyka C#. Soubor XML může obsahovat text pro více metod nebo typů, pokud je výraz XPath dokáže identifikovat.

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

Výstup XML pro tuto metodu je znázorněn v následujícím příkladu:

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

Návod

Tým modulu runtime .NET používá <include> značku ve své dokumentaci. Mnoho příkladů můžete zobrazit vyhledáváním v dotnet/runtime úložišti.

<see>

<see cref="member"/>
<!-- or -->
<see cref="member">Link text</see>
<!-- or -->
<see href="link">Link Text</see>
<!-- or -->
<see langword="keyword"/>
  • cref="member": Odkaz na člena nebo pole, které můžete volat z aktuálního prostředí kompilace. Kompilátor zkontroluje, zda daný element kódu existuje a předává member název elementu ve výstupním XML. Umístit člena do uvozovek ("). Pomocí samostatné koncové značky můžete zadat jiný text crefodkazu.
  • href="link": Odkaz s možností kliknutí na danou adresu URL. Například vytvoří odkaz, <see href="https://github.com">GitHub</see> na který lze kliknout s textem GitHub , na který odkazuje https://github.com. Místo při vytváření odkazů na externí webové stránky používejte hrefcref odkazy cref na kód a nevytváří odkazy umožňující kliknutí pro externí adresy URL.
  • langword="keyword": Klíčové slovo jazyka, například true jedno z dalších platných klíčových slov.

Značka <see> umožňuje zadat odkaz z textu. Slouží <seealso> k označení, že text by se měl umístit do oddílu Viz také. Pomocí atributu cref vytvořte interní hypertextové odkazy na stránky dokumentace pro prvky kódu. Zahrňte parametry typu pro zadání odkazu na obecný typ nebo metodu, například cref="IDictionary{T, U}". Je to také platný atribut, href který funguje jako hypertextový odkaz.

Zde je příklad znázorňující rozdíl mezi cref a href při odkazování na externí adresy URL:

/// <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": Odkaz na člena nebo pole, které můžete volat z aktuálního prostředí kompilace. Kompilátor zkontroluje, zda daný element kódu existuje a předává member název elementu ve výstupním XML. member musí být uveden v uvozovkách (").
  • href="link": Odkaz s možností kliknutí na danou adresu URL. Například vytvoří odkaz, <seealso href="https://github.com">GitHub</seealso> na který lze kliknout s textem GitHub , na který odkazuje https://github.com.

Značka <seealso> umožňuje zadat text, který se může zobrazit v oddílu Viz také . Slouží <see> k zadání odkazu z textu. Značku nemůžete vnořit seealso do značky summary .

Atribut cref

Atribut cref ve značce dokumentace XML znamená "odkaz na kód". Určuje, že vnitřní text značky je prvek kódu, například typ, metoda nebo vlastnost. Nástroje dokumentace, jako je DocFX a Sandcastle , používají cref atributy k automatickému vygenerování hypertextových odkazů na stránku, kde je dokumentován typ nebo člen.

href – atribut

Atribut href znamená odkaz na webovou stránku. Můžete ho použít k přímému odkazování na online dokumentaci k rozhraní API nebo knihovně. Pokud potřebujete odkazovat na externí adresy URL v komentářích dokumentace, použijte href místo cref pro zajištění, že odkazy jsou kliknutelné v popisech IntelliSense a vygenerované dokumentaci.

Obecné typy a metody

<typeparam>

<typeparam name="TResult">The type returned from this method</typeparam>
  • TResult: Název parametru typu. Uzavřete název do uvozovek (").

Značka <typeparam> by měla být použita v komentáři pro obecný typ nebo deklaraci metody k popisu parametru typu. Přidejte značku pro každý parametr typu obecného typu nebo metody. Text značky <typeparam> se zobrazí v IntelliSense.

<typeparamref>

<typeparamref name="TKey"/>
  • TKey: Název parametru typu. Uzavřete název do uvozovek (").

Pomocí této značky můžete uživatelům souboru dokumentace umožnit formátování slova určitým způsobem, například kurzívou.

Uživatelsky definované značky

Všechny značky popsané v tomto článku představují značky rozpoznané kompilátorem jazyka C#. Uživatel ale může definovat vlastní značky. Nástroje, jako je Sandcastle, přinášejí podporu pro další značky jako <event> a <note>dokonce podporují dokumentování oborů názvů. Vlastní nebo interní nástroje pro generování dokumentace lze také použít se standardními značkami a lze podporovat více výstupních formátů z HTML do PDF.

  • Last updated on