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

Este artigo descreve como o Visual Studio pode ajudar a documentar elementos de código, como classes e métodos, gerando automaticamente a estrutura padrão de comentários de documentação em XML. No momento da compilação, pode gerar um ficheiro XML que contenha os comentários da documentação.

Pode distribuir o ficheiro XML gerado pelo compilador juntamente com o seu assembly .NET para que o Visual Studio e outros IDEs possam usar o IntelliSense para mostrar informações rápidas sobre tipos e membros. Também pode correr o ficheiro XML através de ferramentas como DocFX e Sandcastle para gerar sites de referência de APIs.

Permitir a geração de documentação

Alternativamente, pode adicionar as propriedades GenerateDocumentationFile ou DocumentationFile ao seu ficheiro .csproj, .vbproj ou .fsproj . Defina GenerateDocumentationFile para true gerar um ficheiro de documentação com o nome e localização predefinidos. Use a DocumentationFile propriedade para especificar um nome ou localização diferente.

Se usar DocumentationFile sozinho ou com a GenerateDocumentationFile propriedade definida em true, é gerado um ficheiro de documentação com o nome e localização especificados. No entanto, se definires GenerateDocumentationFile para false, nenhum ficheiro de documentação é gerado mesmo que definas a DocumentationFile propriedade.

Ativar atalho de teclado de inserção de comentários

Pode definir a opção Comentários para inserir automaticamente estruturas de comentários XML depois de escrever /// em C# ou ''' no Visual Basic.

1. Na barra de menus do Visual Studio, escolha Ferramentas>Opções.
2. Na caixa de diálogo Opções, navegue até Editor> de TextoC# (ou Visual Basic) >Avançado.
3. Na secção de 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 pretende documentar, por exemplo um método.

2. Efetue uma das seguintes ações:

   • Se o atalho de inserção automática de comentários estiver ativado, escreva /// no C# ou ''' no Visual Basic.
   • No menu Editar, escolhaInserir Comentário>.
   • No clique direito ou no menu de contexto, 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 seguinte GetUserName , o template gera o <summary> elemento, um <param> elemento para o parâmetro e um <returns> elemento para documentar o valor de retorno.

   /// <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. Introduza descrições para cada elemento XML para documentar completamente 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";
    }
   

Podes usar elementos e estilos XML nos comentários que aparecem em Quick Info quando passas o rato sobre o código. Estes elementos incluem estilos itálicos ou a negrito, listas com marcadores ou numeradas, e links clicáveis como cref ou href.

Por exemplo, introduza o seguinte código num ficheiro 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";
}

Ao passar o rato sobre GetUserName, o painel de Informações Rápidas aparece da seguinte forma:

Conteúdo relacionado

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