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

  • Článek

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.

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. Ve všech případech byste měli dodržovat tato doporučení:

  • Z důvodu konzistence by měly být zdokumentovány všechny veřejně viditelné typy a jejich veřejné členy.
  • Soukromé členy lze také zdokumentovat pomocí komentářů XML. Zpřístupňuje ale 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.
  • Text dokumentace by měl být napsán pomocí úplných vět končících úplnými zarážkami.
  • Částečné třídy jsou plně podporované a informace o dokumentaci budou zřetězeny do jedné položky pro každý typ.

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 bude obsahovat komentář s informací, že došlo k chybě.
  • Některé z doporučených značek mají zvláštní význam:
    • Značka <param> se používá k popisu parametrů. Pokud se použije, kompilátor ověří, že parametr existuje a že všechny parametry jsou popsány v dokumentaci. Pokud se ověření nezdaří, kompilátor vydá upozornění.
    • Atribut cref lze připojit 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 příkazy, když hledá typ popsaný v atributu cref .
    • Značka <summary> je používána technologií IntelliSense v sadě Visual Studio 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 je 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:

Komentáře k dokumentaci nelze 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í. Toto kódování je znázorněno v následujícím příkladu.

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

Obecné značky

<Shrnutí>

<summary>description</summary>

Značka <summary> by se měla použít k popisu typu nebo člena typu. Poznámky slouží <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ů.

<Poznámky>

<remarks>
description
</remarks>

Značka <remarks> slouží k přidání informací o typu nebo členu typu a doplnění informací zadaných souhrnem<>. 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

<Vrátí>

<returns>description</returns>

Značka <returns> by měla být použita v komentáři pro deklaraci metody k popisu návratové hodnoty.

<Param>

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

Značka <param> by měla být použita v komentáři pro deklaraci metody popisovat jeden z parametrů 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 dvojitých 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 lze zpracovat tak, aby formátoval toto slovo určitým způsobem, například tučným písmem nebo kurzívou.

<Výjimka>

<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 lze použít 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 prostřednictvím průvodce kódem ve vývojovém prostředí sady Visual Studio .NET, přidá <se pro novou vlastnost souhrnná> značka. 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>

Značka <para> se používá uvnitř značky, například< souhrnu>, <poznámek nebo <návratů>>, a umožňuje přidat 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.

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

Blok <listheader> slouží k definování řádku záhlaví tabulky nebo seznamu definic. Při definování tabulky stačí zadat pouze položku term v záhlaví. Každá položka v seznamu je určena blokem <item> . Při vytváření seznamu definic budete muset zadat obojí term i description. Pro tabulku, seznam s odrážkami nebo číslovaný seznam však stačí zadat položku pro description. Seznam nebo tabulka můžou mít libovolný počet <item> bloků.

<C>

<c>text</c>

Značka <c> poskytuje způsob, jak označit text v popisu jako kód. > Kód slouží <k označení více řádků jako kódu.

<kód>

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

Značka <code> se používá k označení více řádků kódu. Pomocí <jazyka c> označte, že jeden řádek textu v popisu by měl být označen jako kód.

<Příklad>

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

Značka <example> umožňuje určit příklad použití metody nebo jiného člena knihovny. Příkladem obvykle je použití značky 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. Použití inheritdoc eliminuje nežádoucí kopírování a vkládání duplicitních komentářů XML a automaticky udržuje komentáře XML synchronizované. Všimněte si, že když přidáte <inheritdoc> značku k typu, všichni členové zdědí také komentáře.

  • cref: Zadejte člena, ze které má být zděděna dokumentace. Již definované značky aktuálního členu nejsou přepsány zděděnými značkami.
  • path: Dotaz výrazu XPath, který bude mít za následek zobrazení sady uzlů. Tento atribut můžete použít k filtrování značek tak, aby zahrnovaly nebo vyloučily z zděděné dokumentace.

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 lze 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; name bude mít .id
  • id: ID značky, která předchází komentářům. Uzavřete ID do uvozovek (" ").

Značka <include> umožňuje 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>

Tip

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.

<Viz>

<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 člen nebo pole, které je možné 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 člen do uvozovek (" "). Pro "cref" můžete zadat jiný text odkazu pomocí samostatné uzavírací značky.
  • 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.
  • 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. Pomocí <funkce seealso> označte, ž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 k určení odkazu na obecný typ nebo metodu, například cref="IDictionary{T, U}". Je to také platný atribut, href který bude fungovat jako hypertextový odkaz.

<seealso>

<seealso cref="member"/>
<!-- or -->
<seealso href="link">Link Text</seealso>
  • cref="member": Odkaz na člen nebo pole, které je možné 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é . Pomocí <funkce Zobrazit> můžete zadat odkaz z textu. Značku nelze 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ě.

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 dvojitých 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 dvojitých 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 výše uvedené značky 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 dalších značek, jako jsou <události> a <poznámky>, a 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.