Vložení komentářů XML pro generování dokumentace

Tento článek popisuje, jak vám Visual Studio může pomoct dokumentovat prvky kódu, jako jsou třídy a metody, tím, že automaticky vygeneruje standardní strukturu komentářů dokumentace XML. V době kompilace můžete vygenerovat soubor XML, který obsahuje komentáře dokumentace.

Soubor XML vygenerovaný kompilátorem můžete distribuovat spolu s sestavením .NET, aby Visual Studio a další integrované vývojové prostředí mohly pomocí IntelliSense zobrazit rychlé informace o typech a členech. Soubor XML můžete také spustit pomocí nástrojů, jako je DocFX a Sandcastle , a generovat referenční weby rozhraní API.

Poznámka:

Příkaz Vložit komentář pro automatické vložení struktury komentářů dokumentace XML je k dispozici v jazyce C# a Visual Basic. Pro jazyk C++ můžete ručně vložit komentáře dokumentace XML a stále generovat soubory dokumentace XML v době kompilace.

Povolení generování dokumentace

Pokud chcete povolit generování dokumentace, zaškrtněte políčko Vygenerovat soubor obsahující dokumentaci k rozhraní API na kartěVýstup> vlastností projektu.

Ve výchozím nastavení se soubor dokumentace s názvem sestavení s příponou .xml vygeneruje ve stejném adresáři jako sestavení. Pokud chcete pro soubor nakonfigurovat nedefaultní název nebo umístění, zadejte nebo přejděte do alternativního umístění v cestě k souboru dokumentace XML.

Alternativně můžete přidat vlastnosti GenerateDocumentationFile nebo DocumentationFile do souboru .csproj, .vbproj nebo .fsproj . Nastavte GenerateDocumentationFile na true ke vygenerování souboru dokumentace s výchozím názvem a umístěním. DocumentationFile Pomocí vlastnosti zadejte jiný název nebo umístění.

Pokud používáte DocumentationFile samostatně nebo s vlastností nastavenou GenerateDocumentationFile na true, vygeneruje se soubor dokumentace se zadaným názvem a umístěním. Pokud však nastavíte GenerateDocumentationFile hodnotu false, není generován žádný soubor dokumentace, i když nastavíte DocumentationFile vlastnost.

Povolit klávesovou zkratku pro vložení komentáře

Možnost Komentáře můžete nastavit tak, aby se po zadání /// v jazyce C# nebo ''' v jazyce Visual Basic automaticky vkládaly struktury komentářů XML.

1. V řádku nabídek sady Visual Studio zvolte Možnosti nástrojů>.
2. V dialogovém okně Možnosti přejděte na Textový editor>C# (nebo Visual Basic) >Pokročilé.
3. V části Komentáře vyberte nebo zrušte Generovat komentáře dokumentace XML pro \\\ (nebo ''').

Automatické vložení komentáře XML

1. V sadě Visual Studio umístěte kurzor nad prvek, který chcete zdokumentovat, například metodu.

2. Proveďte jednu z následujících akcí:

   • Pokud je povolená klávesová zkratka automatického vkládání komentářů, zadejte /// v jazyce C# nebo ''' v jazyce Visual Basic.
   • V nabídce Upravit zvolte IntelliSense>Vložit komentář.
   • V místní nabídce nebo po kliknutí pravým tlačítkem myši zvolte Fragment>Vložit komentář.

   Struktura komentářů XML je okamžitě generována nad element kódu. Například při komentování následující GetUserName metody šablona vygeneruje <summary> prvek, <param> element pro parametr a <returns> element k dokumentování návratové hodnoty.

   /// <summary>
   /// 
   /// </summary>
   /// <param name="id"></param>
   /// <returns></returns>
   public string GetUserName(int id)
   {
       return "username";
   }
   

   ''' <summary>
   ''' 
   ''' </summary>
   ''' <param name="id"></param>
   ''' <returns></returns>
   Public Function GetUserName(id As Integer) As String
       Return "username"
   End Function
   

3. Zadejte popisy pro každý element XML, který kód plně zdokumentuje. Například:

    /// <summary>
    /// Gets the username associated with the specified ID.
    /// </summary>
    /// <param name="id">The unique user ID.</param>
    /// <returns>A string containing the username for the specified ID.</returns>
    public string GetUserName(int id)
    {
        return "username";
    }
   

Elementy a styly XML můžete použít v komentářích, které se při najetí myší na kód vykreslují v rychlých informacích. Mezi tyto prvky patří kurzíva nebo tučné styly, odrážkové nebo číslované seznamy a klikatelné cref nebo href odkazy.

Do souboru programu jazyka C# zadejte například následující kód:

/// <summary>
/// There are two <see href="https://bing.com">params</see>.
/// <list type="number">
/// <item><param name="id">The user <em>id</em></param></item>
/// <item><param name="username">The user <em>name</em></param></item>
/// </list>
/// </summary>
/// <returns>The <strong>username</strong>.</returns>
public static string GetUserName(int id)
{
    return "username";
}

Když najedete myší na GetUserName, zobrazí se podokno Rychlé informace takto:

Související obsah

• Komentáře k dokumentaci
• Dokumentace XML v jazyce Visual Basic
• Komentáře (C++)
• Dokumentace XML (Visual C++)
• generování kódu