Como: Inserir comentários XML para geração de documentaçãoHow to: Insert XML comments for documentation generation

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.Visual Studio can help you document code elements such as classes and methods, by automatically generating the standard XML documentation comment structure. No tempo de compilação, você pode gerar um arquivo XML contendo os comentários da documentação.At compile time, you can generate an XML file that contains the documentation comments.

Tip

Para obter informações sobre como configurar o nome e o local do arquivo XML gerado, confira Documentar seu código com comentários XML (Guia C#).For information about configuring the name and location of the generated XML file, see Documenting your code with XML comments (C# Guide).

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.The compiler-generated XML file can be distributed alongside your .NET assembly so that Visual Studio and other IDEs can use IntelliSense to show quick information about types and members. Além disso, o arquivo XML pode ser executado por ferramentas como DocFX e Sandcastle para gerar sites de referência de API.Additionally, the XML file can be run through tools like DocFX and Sandcastle to generate API reference websites.

Note

O comando Inserir Comentário, que insere comentários da documentação XML automaticamente está disponível em C# e em Visual Basic.The Insert Comment command that automatically inserts XML documentation comments is available in C# and 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.However, you can manually insert XML documentation comments in C++ files and still generate XML documentation files at compile time.

Para inserir comentários XML para um elemento de códigoTo insert XML comments for a code element

  1. coloque o cursor de texto acima do elemento que você deseja documentar, por exemplo, um método.Place your text cursor above the element you want to document, for example, a method.

  2. Realize um dos seguintes procedimentos:Do one of the following:

    • Digite /// em C# ou ''' em Visual BasicType /// in C#, or ''' in Visual Basic

    • No menu Editar, escolha IntelliSense > Inserir ComentárioFrom the Edit menu, choose IntelliSense > Insert Comment

    • No menu acionado com o botão direito do mouse ou menu de contexto, no elemento de código ou logo acima dele, escolha Snippet de Código > Inserir ComentárioFrom the right-click or context menu on or just above the code element, choose Snippet > Insert Comment

    O modelo XML é gerado imediatamente acima do elemento de código.The XML template is immediately generated above the code element. Por exemplo, quando um método é comentado, ele gera o elemento <summary> , um elemento <param> para cada parâmetro e um elemento <returns> para documentar o valor retornado.For example, when commenting a method, it generates the <summary> element, a <param> element for each parameter, and a <returns> element to document the return value.

    Modelo de comentário XML – C#

    Modelo de comentário XML – Visual Basic

  3. Insira descrições para cada elemento XML para documentar totalmente o elemento de código.Enter descriptions for each XML element to fully document the code element.

    Comentário concluído

Note

Há um opção para ativar/desativar os comentários da documentação XML depois de digitar /// em C# ou ''' em Visual Basic.There is an option to toggle XML documentation comments after typing /// in C# or ''' Visual Basic. Na barra de menus, escolha Ferramentas > Opções para abrir a caixa de diálogo Opções.From the menu bar, choose Tools > Options to open the Options dialog box. Em seguida, navegue até Editor de Texto > C# ou Básico > Avançado.Then, navigate to Text Editor > C# or Basic > Advanced. Na seção Ajuda do Editor, procure a opção Gerar comentários da documentação XML.In the Editor Help section, look for the Generate XML documentation comments option.

Consulte tambémSee also