Como inserir comentários XML para geração de documentação

  • Artigo
  • 2 minutos para o fim da leitura

Aplica-se a:yes Visual Studio noVisual Studio para Mac noVisual Studio Code

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. Para habilitar essa opção, selecione Gerar um arquivo que contém a documentação da API na guiaSaída de Build> das propriedades do projeto.

Dica

Se você quiser configurar um nome e um local não padrão para o arquivo de documentação, adicione a propriedade DocumentationFile ao arquivo .csproj, .vbproj ou .fsproj .

O arquivo XML gerado pelo compilador pode ser distribuído em conjunto 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. Além disso, o arquivo XML pode ser executado por ferramentas como DocFX e Sandcastle para gerar sites de referência de API.

Observação

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

Para inserir comentários XML para um elemento de código

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

  2. Realize um dos seguintes procedimentos:

    • Digite /// em C# ou ''' em Visual Basic

    • No menu Editar, escolha IntelliSense>Inserir Comentário

    • No menu de contexto ou clique com o botão direito do mouse ou no elemento de código ou logo acima, escolhaInserir Comentário do Snippet>

    O modelo XML é gerado imediatamente acima do elemento de código. Por exemplo, ao comentar um método, ele gera o <elemento de resumo> , um <elemento param> para cada parâmetro e um <elemento retorna> para documentar o valor retornado.

    XML comment template - C#

    XML comment template - Visual Basic

  3. Insira descrições para cada elemento XML para documentar totalmente o elemento de código.

    Screenshot showing the completed comment.

Você pode usar estilos em comentários XML que serão renderizados em Informações Rápidas ao passar o mouse sobre o elemento. Esses estilos incluem: itálico, negrito, marcadores e um link clicável.

Screenshot showing the completed comment with style tags for italics, bold, bullets, and a clickable link.

Observação

Há um opção para ativar/desativar os comentários da documentação XML depois de digitar /// em C# ou ''' em Visual Basic. Na barra de menus, escolhaOpçõesde Ferramentas> para abrir a caixa de diálogo Opções. Em seguida, navegue até o Editor> de TextoC# (ou Visual Basic) >Avançado. Na seção Ajuda do Editor, procure a opção Gerar comentários da documentação XML.

Confira também