Visual Studio Desactivar Advertencia de comentario XML faltante

198

Tengo un proyecto con más de 500 Missing XML Comment advertencias. Sé que puedo eliminar la función de comentarios XML o pegar fragmentos de comentarios vacíos en todas partes, pero preferiría una solución genérica en la que pueda hacer un cambio que deshabilite todas las advertencias de este tipo.

Lo que hago ahora es poner

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

o 

#pragma warning disable 1591

Tenía curiosidad por saber si sería posible.

visual-studio-2010 xml-comments Dholakia Nivid
fuente
3
¿Cuál es la pregunta real? ¿Desea conocer otra forma de deshabilitar las advertencias que se generan cuando faltan los comentarios XML? En las propiedades del proyecto, cambie a la pestaña "Compilar" y desmarque "Archivo de documentación XML". Sin embargo, sugeriría no suprimir las advertencias, sino agregar la documentación que falta.
Gorgsenegger
Eso es absolutamente correcto, pero tenía curiosidad acerca de cómo si podemos resolver esto desde un lugar ya que yo era nuevo en esto.
Nivid Dholakia
Estas preguntas relacionadas pueden ayudar: stackoverflow.com/questions/11444631/… stackoverflow.com/questions/3630282/…
Mightymuke
1
La advertencia solo aparece para los miembros que son visibles para otros ensamblados. A menudo las personas hacen clases (e interfaces, enumeraciones, etc.) publicsin una buena razón. En ese caso, una solución fácil (y en mi opinión buena) es simplemente eliminar la palabra public(o reemplazarla con una internalpalabra clave redundante , según el estilo preferido) del tipo de encierro más externo. Luego, todas las advertencias CS1591 sobre este tipo y sus miembros desaparecen. Por supuesto, es posible que deba conservar algunos tipos public. Pero en ese caso, es justo que requiera documentar sus partes públicas correctamente.
Jeppe Stig Nielsen

Respuestas:

318

Como se sugirió anteriormente, en general no creo que estas advertencias deban ignorarse (suprimirse). Para resumir, las formas de evitar la advertencia serían:

  • Suprimir la advertencia al cambiar el proyecto Properties> Build> Errors and warnings> Suppress warningsmediante la introducción de 1591
  • Agregue las etiquetas de documentación XML ( GhostDoc puede ser bastante útil para eso)
  • Suprime la advertencia a través de las opciones del compilador
  • Desactive la casilla de verificación "archivo de documentación XML" en el proyecto Properties> Build>Output
  • Agregue #pragma warning disable 1591en la parte superior del archivo respectivo y #pragma warning restore 1591en la parte inferior
Gorgsenegger
fuente
178
Por favor, no use GhostDoc. Si un comentario puede inferirse del nombre del método, un humano puede inferirlo mejor. Esto agrega valor cero. Sería mejor gastar ese tiempo felicitándote por un método bien nombrado.
JRoughan
24
Tengo que estar en desacuerdo, GhostDoc me ayuda a agregar rápidamente la lista requerida de parámetros y una etiqueta de retorno (si el método no es nulo). Lo uso y me gusta, y conozco a muchas otras personas que también lo hacen. Sin embargo, es cierto que la descripción en el resumen podría necesitar alguna edición, pero esto cuenta para la mayoría de los automatismos en tales casos.
Gorgsenegger 01 de
32
Si todo lo que hizo fue agregar marcadores de posición, sería un buen ahorro de tiempo, pero la cantidad de bases de código que he visto donde los desarrolladores dejan el texto generado hace que pensemos que simplemente no somos lo suficientemente maduros colectivamente como para usarlo. Los comentarios son una muleta (a menudo necesaria) para el código que no se documenta por sí mismo y, al ofrecer accesos directos, esta herramienta tiene un beneficio neto negativo en el código del mundo.
JRoughan
25
@JRoughan: estoy completamente de acuerdo. La peor parte es que, cuando finalmente encuentra el tiempo para documentar adecuadamente su código, estas herramientas hacen que sea imposible determinar cuán exhaustiva es su cobertura de documentación real. Cualquier herramienta que calcule la cobertura de la documentación siempre leerá el 100%. Entonces, literalmente, tiene que pasar por la tarea mentalmente agotadora de leer cada comentario XML y evaluar si es suficiente documentar el código. Habiendo hecho esto en un proyecto grande, puedo decirte que no es divertido en absoluto. Por favor gente! ¡No use estas herramientas de documentación automática!
HiredMind
36
@Gorgsenegger: No en este caso. No es la herramienta la que tiene fallas, es todo el concepto. VS2012 agrega stubs de método / parámetro a comentarios XML estandarizados si eso es lo que desea. Pero agregar comentarios que son simplemente versiones más largas de los nombres de los métodos y llamarlo documentación es solo un desorden visual.
HiredMind
74

Desactive la advertencia: vaya a las propiedades del proyecto (haga clic con el botón derecho en su proyecto y elija Propiedades en el menú contextual) Vaya a la pestaña Generar ingrese la descripción de la imagen aquí

Agregue 1591 al cuadro de texto Suprimir advertencias ingrese la descripción de la imagen aquí

Rao Adnan
fuente
44
Funciona como un encanto con listas separadas por comas: "S125, CS1591, S1172". Después de una construcción, las advertencias desaparecieron.
AFD
9
¡Gracias por responder la pregunta y no dar una conferencia sobre si suprimir o no las advertencias!
Dal
31

También puede modificar el .csprojarchivo de su proyecto para incluir una <noWarn>1591</noWarn>etiqueta dentro del primero <PropertyGroup>. Originalmente del artículo de Alexandru Bucur aquí

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    ...
    <NoWarn>1591</NoWarn>
  </PropertyGroup>
  ...
</Project>
DotNetPadawan
fuente
3
Este debería ser el answear para los días actuales.
Edgar Salazar
3
Convenido. La mayoría de las respuestas no funcionan con otros editores, como Visual Studio Code.
Krzysztof Czelusniak
9

Vaya a las propiedades del proyecto y desactive la opción generar documento XML.

Desmarque el archivo de documentación XML

Recompile y las advertencias deberían desaparecer.

Chris
fuente
2
Este es un buen enfoque siempre que no necesite generar documentos XML y no le importe que los comentarios XML no se validen.
Keith
1
Esto no funciona si desea conservar las advertencias de los archivos que no se generan automáticamente. Eliminar todas las advertencias solo para deshacerme de un subconjunto de advertencias me parece un poco exagerado. Además, en la mayoría de las empresas, es una práctica común crear comentarios XML en todos los archivos que no contienen código generado automáticamente. Además, el usuario solicitó una solución que no simplemente elimine la función de comentarios XML, por lo que esto no responde a la pregunta.
SubliemeSiem
4

Esto habría sido un comentario, pero no pude lograr que se ajustara a la limitación:

Me encantaría deshabilitarlos solo para las importaciones Reference.cs y WebService. En realidad estoy usando una macro para hacerlo para un archivo. Simplemente abra el archivo y ejecute esta macro (Probado en 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 no hay forma de hacer esto automáticamente? Tendría que volver a hacer esto cada vez que el código generado automáticamente anule el archivo.

Kjellski
fuente
2
Creo que esta advertencia no debería aparecer para el contenido generado automáticamente, tal vez tendrá que verificar la configuración correspondiente en las propiedades del proyecto.
Gorgsenegger
1
No, todo se muestra simplemente habilitando las advertencias de XML-Comment. Y no existe tal opción para deshabilitarlo solo para el código autogenerado. Por lo tanto, se corta cuando necesitas regenerar el código.
Kjellski
En las propiedades del proyecto Code Analysis, hay una opción Supress results from generated code. Tener que volver a ejecutar una macro después de cada regeneración de código no es realmente una solución IMO. Si la opción anterior no funciona para usted, ¿quizás el generador de código se pueda ajustar para agregar automáticamente la directiva pragma?
Laoujin
@Laoujin gracias por tu comentario, pero como he mencionado, tampoco me gusta esta solución. No puedo ver una razón para el voto negativo, he usado la configuración que mencionas sin éxito. ¿Hay alguna posibilidad de que pruebe su solución para las importaciones de WebService?
Kjellski