Sdílet prostřednictvím


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 sestavení>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.

Pokud chcete povolit generování dokumentace, zaškrtněte políčko Soubor dokumentace XML v části Výstup sestavení>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í.

Alternativně můžete přidat vlastnosti GenerateDocumentationFile nebo DocumentationFile do souboru .csproj, .vbproj nebo .fsproj. Nastavte GenerateDocumentationFile na true 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.

Povolení klávesové zkratky 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 do rozšířeného textového editoru>C# (nebo Visual Basic).>
  3. V části Komentáře vyberte nebo zrušte výběr možnosti 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 kliknutí pravým tlačítkem myši zvolte Vložit komentář fragmentu>kódu.

    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. Pří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, seznamy s odrážkami nebo číslovanými seznamy a kliknutím 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:

Snímek obrazovky zobrazující dokončený komentář se značkami stylu pro odkaz, číslovaný seznam a kurzívu a tučné formátování