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.

Habilitar a geração de documentação

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