Gerar documentação de função automaticamente no Visual Studio

89

Eu queria saber se existe uma maneira (espero atalho de teclado) para criar cabeçalhos de função de geração automática no Visual Studio.

Exemplo:

Private Function Foo(ByVal param1 As String, ByVal param2 As Integer)

E se tornaria automagicamente algo assim ...


'---------------------------------- 
'Pre: 
'Post:
'Author: 
'Date: 
'Param1 (String): 
'Param2 (Integer): 
'Summary: 
Private Function Foo(ByVal param1 As String, ByVal param2 As Integer)
Ryan M
fonte
1
Se você pousou nesta página porque este recurso parece estar quebrado em seu IDE, você deve garantir que seu código seja compilado e tente novamente. Este recurso não funciona quando seu código contém erros de análise.
krowe2
Como gerar lista de tarefas no xamarin?
Manthan,

Respostas:

158

Faça isso "três marcadores de comentário único"

Em C # é ///

que, por padrão, expõe:

/// <summary>
/// 
/// </summary>
/// <returns></returns>

Aqui estão algumas dicas sobre como editar modelos do VS.

Michael Paulukonis
fonte
7
E no VB.NET são aspas simples triplas (conforme mencionado em outra resposta)
peSHIr
1
Isso é muito legal, não sabia disso
Brendan
A opção "Gerar comentários de documentação XML para ///" não funcionará se a linha anterior sem espaço em branco começar com "///"
Moon Waxing
É possível fazer isso automaticamente em cada método, propriedade e variável? Mesmo que o código já exista?
Robin Bruneel
link de dicas corrigido novamente . maldito seja, teia de mão única!
Michael Paulukonis
48

GhostDoc !

Clique com o botão direito na função, selecione "Documentar" e

private bool FindTheFoo(int numberOfFoos)

torna-se

/// <summary>
/// Finds the foo.
/// </summary>
/// <param name="numberOfFoos">The number of foos.</param>
/// <returns></returns>
private bool FindTheFoo(int numberOfFoos)

(sim, é tudo gerado automaticamente).

Possui suporte para C #, VB.NET e C / C ++. É por padrão mapeado para Ctrl+ Shift+ D.

Lembre-se: você deve adicionar informações além da assinatura do método à documentação. Não pare apenas com a documentação gerada automaticamente. O valor de uma ferramenta como essa é que ela gera automaticamente a documentação que pode ser extraída da assinatura do método, portanto, qualquer informação adicionada deve ser nova .

Dito isso, eu pessoalmente prefiro quando os métodos são totalmente autodocumentados, mas às vezes você terá padrões de codificação que exigem documentação externa e, em seguida, uma ferramenta como esta o poupará de muito trabalho de digitação.

Rasmus Faber
fonte
16
E esse é exatamente o tipo de 'documentação' que eu detesto. Ele apenas adiciona bytes sem me dizer nada que os nomes do método e dos parâmetros já não digam. Não faça isso, sem editar o comentário em algo que valha a pena ... :-(
peSHIr
12
Claro que você deve editá-lo para adicionar informações. Mas, como modelo, é muito bom.
Rasmus Faber
3
@Rasmus: É um template que, para uma boa documentação, deve ser totalmente descartado e reescrito de qualquer maneira, já que não possui conteúdo informativo. Portanto, é realmente mais esforço do que se estivesse apenas em branco.
Joey
35
///

é o atalho para obter o bloco de comentários da Descrição do Método. Mas certifique-se de ter escrito o nome da função e a assinatura antes de adicioná-la. Escreva primeiro o nome da função e a assinatura.

Então, acima do nome da função, basta digitar ///

e você receberá automaticamente

insira a descrição da imagem aqui

Bimzee
fonte
4
bela característica incomum de um post, sua animação.
n611x007
1
Como você fez isso? Eu gosto dessa resposta. Nunca vi isso antes.
Matthis Kohli
2
é legal. uma adição seria parâmetros para a função.
amit jha
19

O Visual Assist também tem uma boa solução e é altamente personalizável.

Depois de ajustá-lo para gerar comentários no estilo doxygen, esses dois cliques produziriam -

/**
* Method:    FindTheFoo
* FullName:  FindTheFoo
* Access:    private 
* Qualifier:
* @param    int numberOfFoos
* @return   bool
*/
private bool FindTheFoo(int numberOfFoos)
{

}

(Nas configurações padrão, é um pouco diferente.)


Editar: A forma de personalizar o texto do 'método do documento' é em VassistX-> Opções do Visual Assist-> Sugestões, selecione 'Editar trechos VA', Idioma: C ++, Tipo: Refatoração, vá para 'Método do documento' e personalize. O exemplo acima é gerado por:

va_doxy

Ofek Shilon
fonte
Por favor, compartilhe como você configurou isso em VA
Damian
Elaborado com a resposta. Espero que isto ajude.
Ofek Shilon
Para inserir o snippet: com o cursor no nome / assinatura do método, alt + shift + q> "método do documento"
Andrew
13

Normalmente, o Visual Studio o cria automaticamente se você adicionar três marcadores de comentário únicos acima do que deseja comentar (método, classe).

Em C #, isso seria ///.

Se o Visual Studio não fizer isso, você pode habilitá-lo em

Opções-> Editor de Texto-> C # -> Avançado

e verificar

Gere comentários de documentação XML para ///

descrição retratada

Domysee
fonte
3

No visual basic, se você criar sua função / sub primeiro, na linha acima, você digita 'três vezes, ele irá gerar automaticamente o xml relevante para documentação. Isso também aparece quando você passa o mouse sobre o intellisense e quando está usando a função.

Paul Ishak
fonte
2

Você pode usar trechos de código para inserir as linhas que desejar.

Além disso, se você digitar três aspas simples ('' ') na linha acima do cabeçalho da função, será inserido o modelo de cabeçalho XML que você pode preencher.

Esses comentários XML podem ser interpretados pelo software de documentação e são incluídos na saída do build como um arquivo assembly.xml. Se você mantiver esse arquivo XML com a DLL e fizer referência a essa DLL em outro projeto, esses comentários se tornam disponíveis no intellisense.

DCNYAM
fonte
Isso é VB.NET: em C # é ///
peSHIr
0

Estou trabalhando em um projeto de código aberto chamado Todoc que analisa palavras para produzir saída de documentação adequada automaticamente ao salvar um arquivo. Respeita os comentários existentes e é muito rápido e fluido.

http://todoc.codeplex.com/

Mathias Lykkegaard Lorenzen
fonte