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

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

Você pode distribuir o arquivo XML gerado pelo compilador junto com o assembly do .NET para que o Visual Studio e outros IDEs possam usar o IntelliSense para mostrar informações rápidas sobre os 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 a estrutura de comentários da documentação XML automaticamente está disponível em C# e em Visual Basic. Para C++, você pode inserir arquivos de comentários da documentação XML manualmente e ainda gerar arquivos da documentação XML no tempo de compilação.

Habilitar a geração de documentação

Para habilitar a geração de documentação, marque a caixa de seleção Gerar um arquivo que contém a 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 com uma extensão de arquivo .xml é gerado no mesmo diretório que o assembly. Se você quiser configurar um nome ou local não padrão para o arquivo, insira ou navegue até um local alternativo em 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 como true para gerar um arquivo de documentação com o nome e o local padrão. Use a propriedade DocumentationFile para especificar um nome ou local diferente.

Se você usar DocumentationFile sozinho ou com a propriedade GenerateDocumentationFile 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 propriedade DocumentationFile.

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 menu do Visual Studio, escolha Ferramentas>Opções.
2. Na caixa de diálogo Opções, navegue até Editor de texto>C# (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 de texto 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 automática de comentários estiver habilitado, digite /// em C# ou ''' em Visual Basic.
   • No menu Editar, escolha IntelliSense>Inserir Comentário.
   • No menu acionado com o botão direito do mouse ou menu de contexto, escolha Snippet>Inserir Comentário.

   A estrutura de comentários XML é gerada imediatamente acima do elemento de código. Por exemplo, ao comentar o seguinte método GetUserName, o modelo gera o elemento <summary>, um elemento <param> para o parâmetro e um elemento <returns> 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 e estilos XML em comentários que serão renderizados em Informações Rápidas ao passar o mouse sobre o código. Esses elementos incluem estilos em itálico ou negrito, listas com marcadores ou numeradas e links cref ou href clicáveis.

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 aparece da seguinte maneira:

Conteúdo relacionado

• Comentários de documentação
• Documentação XML no Visual Basic
• Comentários (C++)
• Documentação XML (Visual C++)
• Geração de código