Visual Studio désactivant l'avertissement de commentaire XML manquant

198

J'ai un projet avec plus de 500 Missing XML Commentavertissements. Je sais que je peux supprimer la fonctionnalité de commentaire XML ou coller des extraits de commentaires vides partout, mais je préférerais une solution générique où je peux apporter une modification qui désactive tous les avertissements de ce type.

Ce que je fais maintenant, c'est mettre

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

ou 

#pragma warning disable 1591

était juste curieux de savoir si cela serait possible.

visual-studio-2010 xml-comments Nhol Dholakia
la source
3
Quelle est la vraie question? Souhaitez-vous connaître une autre façon de désactiver les avertissements générés lorsque les commentaires XML sont manquants? Dans les propriétés du projet, passez à l'onglet "Construire" et décochez "Fichier de documentation XML". Cependant, je suggère de ne pas supprimer les avertissements, mais d'ajouter la documentation manquante.
Gorgsenegger
C'est tout à fait correct, mais je voulais simplement savoir comment résoudre ce problème à partir d'un seul endroit car j'étais nouveau dans ce domaine.
Nivid Dholakia
Ces questions connexes peuvent aider: stackoverflow.com/questions/11444631/… stackoverflow.com/questions/3630282/…
Mightymuke
1
L'avertissement n'apparaît que pour les membres visibles par les autres assemblys. Souvent, les gens font des classes (et des interfaces, des énumérations, etc.) publicsans raison valable. Dans ce cas, une solution facile (et à mon avis bonne) consiste simplement à supprimer le mot public(ou à le remplacer par un internalmot clé redondant , selon le style préféré) du type de boîtier le plus à l'extérieur. Ensuite, tous les avertissements CS1591 concernant ce type et ses membres disparaissent. Bien sûr, vous devrez peut-être conserver certains types public. Mais dans ce cas, il est juste que vous ayez besoin de documenter correctement leurs parties publiques.
Jeppe Stig Nielsen

Réponses:

318

Comme suggéré ci-dessus, en général, je ne pense pas que ces avertissements doivent être ignorés (supprimés). Pour résumer, les moyens de contourner l'avertissement seraient les suivants:

  • Supprimer l'avertissement en changeant le projet Properties> Build> Errors and warnings> Suppress warningsen entrant 1591
  • Ajoutez les balises de documentation XML ( GhostDoc peut être très pratique pour cela)
  • Supprimer l'avertissement via les options du compilateur
  • Décochez la case « Fichier de documentation XML » dans le projet Properties> Build>Output
  • Ajouter #pragma warning disable 1591en haut du fichier respectif et #pragma warning restore 1591en bas
Gorgsenegger
la source
178
Veuillez ne pas utiliser GhostDoc. Si un commentaire peut être déduit du nom de la méthode, il peut être mieux déduit par un humain. Cela n'ajoute aucune valeur. Il serait préférable de consacrer ce temps à vous féliciter pour une méthode bien nommée.
JRoughan
24
Je dois être en désaccord, GhostDoc m'aide à ajouter rapidement la liste requise des paramètres et une balise de retour (si la méthode n'est pas nulle). J'utilise et j'aime bien, et je connais pas mal d'autres personnes qui le font aussi. Il est vrai, cependant, que la description dans le résumé peut nécessiter quelques modifications, mais cela compte pour la plupart des automatismes dans de tels cas.
Gorgsenegger
32
Si tout ce qu'il a fait était d'ajouter des espaces réservés, ce serait un petit gain de temps, mais le nombre de bases de code que j'ai vues où les développeurs laissent le texte généré nous fait penser que nous ne sommes tout simplement pas suffisamment matures collectivement pour l'utiliser. Les commentaires sont une béquille (souvent nécessaire) pour le code qui n'est pas auto-documenté et en offrant des raccourcis, cet outil a un avantage net négatif sur le code du monde.
JRoughan
25
@JRoughan: Je suis entièrement d'accord. Le pire, c'est que lorsque vous trouvez enfin le temps de documenter correctement votre code, ces outils ne permettent pas de déterminer à quel point votre couverture de documentation est complète. Tout outil qui calcule la couverture de la documentation sera toujours lu à 100%. Vous devez donc littéralement passer par la tâche épuisante mentalement de lire chaque commentaire XML et d'évaluer s'il est suffisant de documenter le code. Après avoir fait cela sur un grand projet, je peux vous dire que ce n'est pas amusant du tout. Faites plaisir aux gens! N'utilisez pas ces outils de documentation automatique!
HiredMind
36
@Gorgsenegger: Pas dans ce cas. Ce n'est pas l'outil qui est défectueux, c'est tout le concept. VS2012 ajoute des talons de méthode / paramètre aux commentaires XML standardisés si c'est ce que vous voulez. Mais ajouter des commentaires qui sont simplement des versions plus longues des noms de méthode et l'appeler documentation n'est qu'un désordre visuel.
HiredMind
74

Désactivez l'avertissement: allez dans les propriétés du projet (faites un clic droit sur votre projet et choisissez Propriétés dans le menu contextuel) allez dans l'onglet Build entrez la description de l'image ici

Ajoutez 1591 à la zone de texte Supprimer les avertissements entrez la description de l'image ici

Rao Adnan
la source
4
Fonctionne comme un charme avec des listes séparées par des virgules: "S125, CS1591, S1172". Après une construction, les warings ont disparu.
AFD
9
Merci d'avoir répondu à la question et de ne pas avoir indiqué s'il fallait ou non supprimer les avertissements!
Dal
31

Vous pouvez également modifier le .csprojfichier de votre projet pour inclure une <noWarn>1591</noWarn>balise à l'intérieur du premier <PropertyGroup>. Originaire de l'article d' Alexandru Bucur ici

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    ...
    <NoWarn>1591</NoWarn>
  </PropertyGroup>
  ...
</Project>
DotNetPadawan
la source
3
Cela devrait être la réponse pour les jours actuels.
Edgar Salazar
3
D'accord. La plupart des réponses ne fonctionnent pas avec d'autres éditeurs, tels que Visual Studio Code.
Krzysztof Czelusniak
9

Allez dans les propriétés du projet et décochez l'option de génération de document XML.

Décochez le fichier de documentation XML

Recompilez et les avertissements devraient disparaître.

Chris
la source
2
C'est une bonne approche tant que vous n'avez pas besoin de générer les documents XML et que cela ne vous dérange pas que les commentaires XML ne soient pas validés.
Keith
1
Cela ne fonctionne pas si vous souhaitez conserver les avertissements des fichiers qui ne sont pas générés automatiquement. Supprimer tous les avertissements juste pour se débarrasser d'un sous-ensemble d'avertissements me semble un peu exagéré. En outre, dans la plupart des entreprises, il est courant de créer des commentaires XML dans tous les fichiers qui ne contiennent pas de code généré automatiquement. De plus, l'utilisateur a demandé une solution qui ne supprime pas simplement la fonction de commentaire XML, ce qui ne répond donc pas à la question.
SubliemeSiem
4

Cela aurait été un commentaire mais je n'ai pas réussi à l'adapter à la limitation:

J'aimerais les désactiver uniquement pour les importations Reference.cs et WebService. En fait, j'utilise une macro pour le faire pour un fichier. Ouvrez simplement le fichier et exécutez cette macro (Testé dans 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

Il n'y a vraiment aucun moyen de le faire automatiquement? Vous devrez refaire cela chaque fois que le code généré automatiquement remplace le fichier.

Kjellski
la source
2
Je pense que cet avertissement ne devrait pas apparaître pour le contenu généré automatiquement, vous devrez peut-être vérifier le paramètre correspondant dans les propriétés du projet.
Gorgsenegger
1
Non, tout est montré en activant simplement les avertissements de commentaire XML. Et il n'y a pas une telle option pour le désactiver uniquement pour le code généré automatiquement. À cet effet, il est coupé lorsque vous avez besoin de régénérer le code.
Kjellski
Sous les propriétés du projet Code Analysis, il y a une option Supress results from generated code. Devoir réexécuter une macro après chaque régénération de code n'est pas vraiment une solution IMO. Si l'option ci-dessus ne fonctionne pas pour vous, peut-être que le générateur de code peut être ajusté pour ajouter automatiquement la directive pragma à la place?
Laoujin
@Laoujin merci pour votre commentaire, mais comme je l'ai mentionné, je n'aime pas non plus cette solution. Je ne vois pas de raison pour le downvote, j'ai utilisé le paramètre que vous mentionnez sans succès. Avez-vous des chances d'essayer votre solution pour les importations WebService?
Kjellski