Visual Studio Desabilitando o aviso de comentário XML ausente

198

Eu tenho um projeto com mais de 500 Missing XML Commentavisos. Eu sei que posso remover o recurso XML Comment ou colar trechos de comentários vazios em todos os lugares, mas prefiro uma solução genérica na qual eu possa fazer uma alteração que desative todos os avisos desse tipo.

O que eu faço agora é colocar

///<Summary>
/// 
///</Summary>

ou

#pragma warning disable 1591

estava curioso para saber se isso seria possível.

visual-studio-2010 xml-comments

— Nivid Dholakia
fonte

3

Qual é a pergunta real? Deseja conhecer outra maneira de desativar os avisos gerados quando faltam os comentários XML? Nas propriedades do projeto, mude para a guia "Build" e desmarque "arquivo de documentação XML". No entanto, sugiro não suprimir os avisos, mas adicionar a documentação ausente.

— Gorgsenegger

Isso é absolutamente correto, mas estava curioso para saber como resolver isso de um lugar, pois eu era novo nisso.

— Nivid Dholakia

Estas perguntas relacionadas podem ajudar: stackoverflow.com/questions/11444631/… stackoverflow.com/questions/3630282/…

— Mightymuke

1

O aviso aparece apenas para membros visíveis para outras montagens. Muitas vezes, as pessoas fazem aulas (e interfaces, enumerações, etc.) publicsem uma boa razão. Nesse caso, uma solução fácil (e na minha opinião boa) é apenas remover a palavra public(ou substituí-la por uma internalpalavra-chave redundante , dependendo do estilo preferido) do tipo de invólucro mais externo. Todos os avisos do CS1591 sobre esse tipo e seus membros desaparecem. Claro que você ainda precisa manter alguns tipos public. Mas, nesse caso, é justo que você exija a documentação adequada de suas partes públicas.

— Jeppe Stig Nielsen

318

Como sugerido acima, em geral, não acho que esses avisos devam ser ignorados (suprimidos). Para resumir, as maneiras de contornar o aviso seriam:

Suprimir o aviso, alterando o projeto Properties> Build> Errors and warnings> Suppress warningsinserindo 1591
Adicione as tags de documentação XML (o GhostDoc pode ser bastante útil para isso)
Suprimir o aviso via opções do compilador
Desmarque a opção "arquivo de documentação XML" checkbox no projeto Properties> Build>Output
Adicione #pragma warning disable 1591na parte superior do respectivo arquivo e #pragma warning restore 1591na parte inferior

— Gorgsenegger
fonte

178

Por favor, não use o GhostDoc. Se um comentário puder ser inferido a partir do nome do método, ele poderá ser inferido melhor por um ser humano. Isso adiciona valor zero. É melhor gastar esse tempo parabenizando-se por um método bem conhecido.

— JRoughan

24

Eu tenho que discordar, o GhostDoc me ajuda a adicionar rapidamente a lista necessária de paramaters e uma tag de retorno (se o método não for nulo). Eu uso e gosto, e conheço muitas outras pessoas que também. É verdade, no entanto, que a descrição no resumo pode precisar de alguma edição, mas isso conta para a maioria dos automatismos nesses casos.

— Gorgsenegger 01/07/2012

32

Se tudo o que fizéssemos foi adicionar espaços reservados, economizaria um pouco de tempo, mas o número de bases de código que vi onde os desenvolvedores deixam o texto gerado faz com que pensemos que não somos coletivamente maduros o suficiente para usá-lo. Os comentários são uma muleta (geralmente necessária) para o código que não é auto-documentado e, oferecendo atalhos, essa ferramenta tem um benefício líquido negativo no código do mundo.

— perfil completo de JRoughan

25

@JRoughan: Concordo plenamente. A pior parte é que, quando você finalmente encontra tempo para documentar corretamente seu código, essas ferramentas tornam impossível saber o quão abrangente é sua cobertura de documentação real. Qualquer ferramenta que calcule a cobertura da documentação sempre lerá 100%. Portanto, você literalmente precisa executar a tarefa mentalmente exaustiva de ler todos os comentários XML e avaliar se é suficiente documentar o código. Tendo feito isso em um projeto grande, posso dizer, não é nada divertido. Por favor pessoal! Não use essas ferramentas de documentação automática!

— HiredMind

36

@Gorgsenegger: Não neste caso. Não é a ferramenta que apresenta falhas, é todo o conceito. O VS2012 adiciona stubs de método / parâmetro a comentários XML padronizados, se é isso que você deseja. Mas adicionar comentários que são simplesmente versões mais longas dos nomes dos métodos e chamá-lo de documentação é apenas desorganização visual.

— precisa saber é o seguinte

74

Desabilite o aviso: Vá para as propriedades do projeto (clique com o botão direito do mouse em seu projeto e escolha Propriedades no menu de contexto) Vá para a guia Compilar

Adicione 1591 à caixa de texto Suprimir avisos

— Rao Adnan
fonte

4

Funciona como um encanto com listas separadas por vírgula: "S125, CS1591, S1172". Após uma construção, os warings desapareceram.

— AFD

9

Obrigado por responder à pergunta e por não dar uma palestra sobre se deve ou não suprimir os avisos!

— Dal

31

Você também pode modificar o .csprojarquivo do seu projeto para incluir uma <noWarn>1591</noWarn>tag dentro da primeira <PropertyGroup>. Originalmente do artigo de Alexandru Bucur aqui

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    ...
    <NoWarn>1591</NoWarn>
  </PropertyGroup>
  ...
</Project>

— DotNetPadawan
fonte

3

Essa deve ser a resposta para os dias atuais.

— Edgar Salazar

3

Acordado. A maioria das respostas não funciona com outros editores, como o Visual Studio Code.

— Krzysztof Czelusniak 22/02/19

9

Vá para as propriedades do projeto e desmarque a opção gerar documento XML.

Recompile e os avisos devem desaparecer.

— Chris
fonte

2

Essa é uma boa abordagem, desde que você não precise gerar os documentos XML e não se importe de que os comentários XML não sejam validados.

— Keith

1

Isso não funciona se você deseja manter os avisos de arquivos que não são gerados automaticamente. Remover todos os avisos apenas para se livrar de um subconjunto de avisos me parece um pouco exagerado. Além disso, na maioria das empresas, é prática comum criar comentários XML em todos os arquivos que não contêm código gerado automaticamente. Além disso, o usuário solicitou uma solução que não remova simplesmente o recurso de comentário XML, portanto, isso não responde à pergunta.

— SubliemeSiem

4

Isso teria sido um comentário, mas não consegui encaixar na limitação:

Gostaria de desativá-los apenas para as importações Reference.cs e WebService. Na verdade, estou usando uma macro para fazer isso em um arquivo. Basta abrir o arquivo e executar esta macro (Testada no VS2010):

Sub PragmaWarningDisableForOpenFile()
    DTE.ActiveDocument.Selection.StartOfDocument()
    DTE.ActiveDocument.Selection.NewLine()
    DTE.ActiveDocument.Selection.LineUp()
    DTE.ActiveDocument.Selection.Insert("#pragma warning disable 1591")
    DTE.ActiveDocument.Selection.EndOfDocument()
    DTE.ActiveDocument.Selection.NewLine()
    DTE.ActiveDocument.Selection.Insert("#pragma warning restore 1591")
    DTE.ActiveDocument.Save()
End Sub

Realmente não há como fazer isso automaticamente? Você precisaria refazer isso sempre que o código gerado automaticamente substituir o arquivo.

— Kjellski
fonte

2

Acho que esse aviso não deve aparecer para conteúdo gerado automaticamente, talvez você precise verificar a configuração correspondente nas propriedades do projeto.

— Gorgsenegger

1

Não, tudo é mostrado apenas ativando os avisos XML-Comment. E não existe essa opção para desativá-lo apenas para código gerado automaticamente. Para isso, você deve recortar quando precisar regenerar o código.

— Kjellski

Nas propriedades do projeto Code Analysis, há uma opção Supress results from generated code. Ter que executar novamente uma macro após cada regeneração de código não é realmente uma solução IMO. Se a opção acima não funcionar para você, talvez o gerador de código possa ser ajustado para adicionar automaticamente a diretiva pragma?

— Laoujin

@ Laoujin obrigado pelo seu comentário, mas como já mencionei, também não gosto dessa solução. Não vejo uma razão para o voto negativo, usei a configuração mencionada sem sucesso. Alguma chance de você experimentar sua solução para importações de WebService?

— Kjellski