Compartilhar via

Inserir comentários XML para geração de documentação

Este artigo descreve como o Visual Studio pode ajudá-lo a documentar elementos de código, como classes e métodos, gerando automaticamente a estrutura de comentários da documentação XML padrão. No momento da compilação, você pode gerar um arquivo XML que contém os comentários da documentação.

Você pode distribuir o arquivo XML gerado pelo compilador junto com o assembly .NET para que o Visual Studio e outros IDEs possam usar o IntelliSense para mostrar informações rápidas sobre tipos e membros. Você também pode executar o arquivo XML por meio de ferramentas como DocFX e Sandcastle para gerar sites de referência de API.

Observação

O comando Inserir Comentário para inserir automaticamente a estrutura de comentários da documentação XML está disponível no C# e no Visual Basic. Para C++, você pode inserir manualmente comentários de documentação XML e ainda gerar arquivos de documentação XML em tempo de compilação.

Habilitar geração de documentação

Para habilitar a geração de documentação, selecione a opção Gerar arquivo contendo documentação da API na guia Build>Saída das propriedades do projeto.

Por padrão, um arquivo de documentação com o mesmo nome do assembly, mas com a extensão .xml, é gerado no mesmo diretório que o assembly. Se você quiser configurar um nome não padrão ou um local para o arquivo, insira ou navegue até um local alternativo no caminho do arquivo de documentação XML.

Como alternativa, você pode adicionar as propriedades GenerateDocumentationFile ou DocumentationFile ao arquivo .csproj, .vbproj ou .fsproj . Defina GenerateDocumentationFile para true para gerar um arquivo de documentação com o nome e o local padrão. Use a DocumentationFile propriedade para especificar um nome ou local diferente.

Se você usar DocumentationFile por si só ou com a GenerateDocumentationFile propriedade definida como true, um arquivo de documentação com o nome e o local especificados será gerado. No entanto, se você definir GenerateDocumentationFile como false, nenhum arquivo de documentação será gerado mesmo se você definir a DocumentationFile propriedade.

Habilitar atalho de teclado de inserção de comentário

Você pode definir a opção Comentários para inserir automaticamente estruturas de comentário XML depois de digitar /// em C# ou ''' no Visual Basic.

  1. Na barra de menus do Visual Studio, escolha Opções de Ferramentas>.
  2. Na caixa de diálogo Opções, navegue até o Editor> de TextoC# (ou Visual Basic) >Avançado.
  3. Na seção Comentários, selecione ou desmarque Gerar comentários de documentação XML para \\\ (ou '').

Inserir automaticamente um comentário XML

  1. No Visual Studio, coloque o cursor acima do elemento que você deseja documentar, por exemplo, um método.

  2. Execute uma das seguintes ações:

    • Se o atalho de inserção de comentário automático estiver habilitado, digite /// em C#ou ''' no Visual Basic.
    • No menu Editar, escolha InserirComentário>.
    • No menu de contexto ou clique com o botão direito do mouse, escolha Snippet>Inserir Comentário.

    A estrutura de comentários XML é imediatamente gerada acima do elemento de código. Por exemplo, ao comentar o método a seguir GetUserName , o modelo gera o <summary> elemento, um <param> elemento para o parâmetro e um <returns> elemento para documentar o valor retornado.

    /// <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. Insira descrições para cada elemento XML para documentar totalmente o código. Por exemplo:

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

Você pode usar elementos XML e estilos em comentários que são renderizados em Informações Rápidas quando você passa o mouse sobre o código. Esses elementos incluem estilos itálicos ou em negrito, listas com marcadores ou numeradas, e links clicáveis cref ou href.

Por exemplo, insira o seguinte código em um arquivo de programa C#:

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

Quando você passa o mouse sobre GetUserName, o painel Informações Rápidas é exibido da seguinte maneira:

Captura de tela mostrando o comentário concluído com marcas de estilo para um link clicável, uma lista numerada e formatação itálica e em negrito.

Conteúdo relacionado

  • Last updated on