Como ter comentários no IntelliSense para função no Visual Studio?

139

No Visual Studio e C #, ao usar uma função interna como ToString (), o IntelliSense mostra uma caixa amarela explicando o que faz.

texto alternativo texto alternativo

Como posso obter isso para funções e propriedades que escrevo?

Todos
fonte

Respostas:

215

Para gerar uma área em que você pode especificar uma descrição para a função e cada parâmetro para a função, digite o seguinte na linha antes da sua função e pressione Enter:

  • C #: ///

  • VB: '''

Consulte Tags recomendadas para comentários da documentação (Guia de programação em C #) para obter mais informações sobre o conteúdo estruturado que você pode incluir nesses comentários.

Solmead
fonte
2
Para enfatizar: Isso é barra tripla em C ++ / C # (comentários normais são barra dupla). E no VB, suas duas aspas simples, não uma aspas dupla.
22415 abelenky
1
É realmente três aspas simples em VB
Joel Coehoorn
1
Na verdade, no VB, são três aspas simples: '' ''
hometoast 9/02/09
2
Como alternativa, em um arquivo VB, você pode clicar com o botão direito do mouse em uma função ou classe e clicar em "Inserir comentário". Para C # você pode usar StyleCop que irá pedir-lhe para escrever bons cabeçalhos de documentação
user1069816
O GhostDoc é uma ótima ferramenta que pode adicionar muito texto nos comentários para você. Submain.com/products/ghostdoc.aspx
Karl Gjertsen
74

O que você precisa é de comentários xml - basicamente, eles seguem esta sintaxe (conforme vagamente descrita por Solmead):

C #

///<summary>
///This is a description of my function.
///</summary>
string myFunction() {
     return "blah";
}

VB

'''<summary>
'''This is a description of my function.
'''</summary>
Function myFunction() As String
    Return "blah"
End Function
Tomas Aschan
fonte
23

<c>text</c>- O texto que você gostaria de indicar como código.
A tag < c > fornece uma maneira de indicar que o texto em uma descrição deve ser marcado como código. Use < código > para indicar várias linhas como código.

<code>content</code>- O texto que você deseja marcar como código.
A tag < code > fornece uma maneira de indicar várias linhas como código. Use < c > para indicar que o texto em uma descrição deve ser marcado como código.

<example>description</example>- Uma descrição do exemplo de código.
A tag < example > permite especificar um exemplo de como usar um método ou outro membro da biblioteca. Isso geralmente envolve o uso da tag < code >.

<exception cref="member">description</exception>- Uma descrição da exceção.
A tag < exception > permite especificar quais exceções podem ser lançadas. Essa tag pode ser aplicada às definições de métodos, propriedades, eventos e indexadores.

<include file='filename' path='tagpath[@name="id"]' />
A tag < include > permite fazer referência a comentários em outro arquivo que descrevem os tipos e membros no seu código-fonte. Essa é uma alternativa para colocar comentários da documentação diretamente no seu arquivo de código-fonte. Ao colocar a documentação em um arquivo separado, você pode aplicar o controle de origem à documentação separadamente do código-fonte. Uma pessoa pode fazer o check-out do arquivo de código-fonte e outra pessoa pode fazer o check-out do arquivo de documentação. A tag < include > usa a sintaxe XML XPath. Consulte a documentação do XPath para obter formas de personalizar seu uso < include >.

<list type="bullet" | "number" | "table">
    <listheader>
        <term>term</term>
        <description>description</description>
    </listheader>
    <item>
        <term>term</term>
        <description>description</description>
    </item>
</list>

O bloco < listheader > é usado para definir a linha do cabeçalho de uma tabela ou lista de definições. Ao definir uma tabela, você só precisa fornecer uma entrada para o termo no cabeçalho. Cada item da lista é especificado com um bloco < item >. Ao criar uma lista de definições, você precisará especificar o termo e a descrição. No entanto, para uma tabela, lista com marcadores ou lista numerada, você só precisa fornecer uma entrada para descrição. Uma lista ou tabela pode ter quantos blocos < item > forem necessários.

<para>content</para>
A marca < para > deve ser usada dentro de uma marca, como < resumo >, < comentários > ou < retornos > e permite adicionar estrutura ao texto.

<param name="name">description</param>
A tag < param > deve ser usada no comentário para uma declaração de método para descrever um dos parâmetros para o método. Para documentar vários parâmetros, use várias tags < param >.
O texto para a marca < param > será exibido no IntelliSense, o Pesquisador de Objetos e no Relatório da Web de Comentários de Código.

<paramref name="name"/>
A tag < paramref > fornece uma maneira de indicar que uma palavra no código comenta, por exemplo, em um bloco < summary > ou < remarks > se refere a um parâmetro. O arquivo XML pode ser processado para formatar essa palavra de alguma maneira distinta, como uma fonte em negrito ou itálico.

< permission cref="member">description</permission>
O < autorização > tag permite documentar o acesso de um membro. A classe PermissionSet permite especificar o acesso a um membro.

<remarks>description</remarks>
A tag < remarks > é usada para adicionar informações sobre um tipo, complementando as informações especificadas com < summary >. Esta informação é exibida no Pesquisador de objetos.

<returns>description</returns>
A tag < Returns > deve ser usada no comentário para uma declaração de método para descrever o valor de retorno.

<see cref="member"/>
A tag < see > permite especificar um link a partir do texto. Use < seealso > para indicar que o texto deve ser colocado na seção Consulte também. Use o atributo cref para criar hiperlinks internos para páginas de documentação para elementos de código.

<seealso cref="member"/>
A tag < seealso > permite especificar o texto que você deseja que apareça na seção Consulte também. Use < see > para especificar um link a partir do texto.

<summary>description</summary>
A tag < summary > deve ser usada para descrever um tipo ou um membro de tipo. Use < remarks > para adicionar informações suplementares a uma descrição do tipo. Use o atributo cref para permitir que ferramentas de documentação como Sandcastle criem hiperlinks internos para páginas de documentação para elementos de código. O texto para a tag < summary > é a única fonte de informações sobre o tipo no IntelliSense e também é exibido no Pesquisador de objetos.

<typeparam name="name">description</typeparam>
A tag < typeparam > deve ser usada no comentário para uma declaração genérica de tipo ou método para descrever um parâmetro de tipo. Adicione uma tag para cada parâmetro de tipo do tipo ou método genérico. O texto da marca < typeparam > será exibido no IntelliSense, o relatório da Web sobre comentários do código do Pesquisador de Objetos.

<typeparamref name="name"/>
Use esta tag para permitir que os consumidores do arquivo de documentação formatem a palavra de alguma maneira distinta, por exemplo, em itálico.

<value>property-description</value>
A tag < value > permite descrever o valor que uma propriedade representa. Observe que quando você adiciona uma propriedade por meio do assistente de código no ambiente de desenvolvimento do Visual Studio .NET, ele adiciona uma marca < summary > à nova propriedade. Você deve adicionar manualmente uma tag < value > para descrever o valor que a propriedade representa.

Máx.
fonte
11

Faça comentários XML, como este

/// <summary>
/// This does something that is awesome
/// </summary>
public void doesSomethingAwesome() {}
Michael Walts
fonte
6
Para parâmetros, adicione:///<param name="paramName">Tralala</param>
The Oddler
10

use /// para iniciar cada linha do comentário e fazer com que o comentário contenha o xml apropriado para o leitor de metadados.

///<summary>
/// this method says hello
///</summary>
public void SayHello();

Embora pessoalmente, acredito que esses comentários geralmente sejam equivocados, a menos que você esteja desenvolvendo classes em que o código não pode ser lido por seus consumidores.

DevelopingChris
fonte
2
eles são bons para lembretes de atalhos ou em qualquer lugar onde você tenha um código de biblioteca onde talvez o código seja legível, mas é preciso um pouco de trabalho extra para chegar a ele.
Joel Coehoorn
1
Concordo com você em teoria, mas se você usar essa coisa de ghostdoc, estará aumentando a relação ruído / sinal a tal ponto que o restante dos comentários será inútil.
DevelopingChris
9

Esses são chamados de comentários XML . Eles fazem parte do Visual Studio desde sempre.

Você pode facilitar o processo de documentação usando o GhostDoc , um suplemento gratuito para o Visual Studio que gera comentários de documentos XML para você. Basta colocar o cursor no método / propriedade que deseja documentar e pressionar Ctrl-Shift-D.

Aqui está um exemplo de uma das minhas postagens .

Espero que ajude :)

Igal Tabachnik
fonte
6

No CSharp, se você criar o contorno do método / função com o Parms, quando adicionar as três barras, ele gerará automaticamente a seção de resumo e parms.

Então eu coloquei:

public string myMethod(string sImput1, int iInput2)
{
}

Em seguida, coloquei os três /// antes e o Visual Studio me deu o seguinte:

/// <summary>
/// 
/// </summary>
/// <param name="sImput1"></param>
/// <param name="iInput2"></param>
/// <returns></returns>
public string myMethod(string sImput1, int iInput2)
{
}
Semperfi89
fonte
6

Defina métodos como este e você receberá a ajuda de que precisa.

    /// <summary>
    /// Adds two numbers and returns the result
    /// </summary>
    /// <param name="first">first number to add</param>
    /// <param name="second">second number to </param>
    /// <returns></returns>
    private int Add(int first, int second)
    {
        return first + second;
    }

Captura de tela do uso do código

Recev Yildiz
fonte
2

Todas essas outras respostas fazem sentido, mas são incompletas. O Visual Studio processará comentários XML, mas você precisa ativá-los. Veja como fazer isso:

O Intellisense usará os comentários XML inseridos no código-fonte, mas você deve habilitá-los através das Opções do Visual Studio. Ir para Tools> Options> Text Editor. Para o Visual Basic, ative a configuração Advanced> Generate XML documentation comments for '''. Para C #, ative a configuração Advanced> Generate XML documentation comments for ///. O Intellisense usará os comentários resumidos quando inseridos. Eles estarão disponíveis em outros projetos após a compilação do projeto referenciado.

Para criar externo documentação, você precisa gerar um arquivo XML através do Project Settings> Build> XML documentation file:caminho que os controles do compilador /docopção. Você precisará de uma ferramenta externa que leve o arquivo XML como entrada e gere a documentação em seus formatos de saída escolhidos.

Esteja ciente de que a geração do arquivo XML pode aumentar visivelmente o tempo de compilação.

Suncat2000
fonte
1

Além disso, o documento fantasma do suplemento do visual studio tentará criar e preencher os comentários do cabeçalho a partir do nome da sua função.

Mark Rogers
fonte
0

Solmead tem a resposta correta. Para obter mais informações, consulte Comentários XML .

Ed S.
fonte