Visual Studio Deaktivieren fehlender XML-Kommentar Warnung

197

Ich habe ein Projekt mit über 500 Missing XML CommentWarnungen. Ich weiß, dass ich die XML-Kommentarfunktion entfernen oder überall leere Kommentarausschnitte einfügen kann, aber ich würde eine generische Lösung bevorzugen, bei der ich eine Änderung vornehmen kann, die alle Warnungen dieses Typs deaktiviert.

Was ich gerade mache, ist Putten

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

oder

#pragma warning disable 1591

war nur neugierig, ob es möglich wäre.

visual-studio-2010 xml-comments Nivid Dholakia
quelle

3

Was ist die eigentliche Frage? Möchten Sie eine andere Möglichkeit kennen, um die Warnungen zu deaktivieren, die generiert werden, wenn die XML-Kommentare fehlen? Wechseln Sie in den Projekteigenschaften zur Registerkarte "Erstellen" und deaktivieren Sie "XML-Dokumentationsdatei". Ich würde jedoch vorschlagen, die Warnungen nicht zu unterdrücken, sondern die fehlende Dokumentation hinzuzufügen.

Gorgsenegger

Das ist absolut richtig, aber ich war nur neugierig, wie wir das von einem Ort aus lösen können, da ich neu in diesem Bereich war.

Nivid Dholakia

Diese verwandten Fragen können helfen: stackoverflow.com/questions/11444631/… stackoverflow.com/questions/3630282/…

Mightymuke

1

Die Warnung wird nur für Mitglieder angezeigt, die für andere Assemblys sichtbar sind. Oft machen Leute Klassen (und Schnittstellen, Aufzählungen usw.) publicohne guten Grund. In diesem Fall besteht eine einfache (und meiner Meinung nach gute) Lösung darin, das Wort einfach aus dem äußersten umschließenden Typ zu entfernen public(oder es durch ein redundantes internalSchlüsselwort zu ersetzen , abhängig vom bevorzugten Stil). Dann verschwinden alle CS1591-Warnungen über diesen Typ und seine Mitglieder. Natürlich müssen Sie möglicherweise noch einige Typen behalten public. In diesem Fall ist es jedoch fair, dass Sie die öffentlichen Teile ordnungsgemäß dokumentieren müssen.

Jeppe Stig Nielsen

318

Wie oben vorgeschlagen, denke ich im Allgemeinen nicht, dass diese Warnungen ignoriert (unterdrückt) werden sollten. Zusammenfassend lässt sich sagen, dass die Warnung wie folgt umgeht:

Unterdrückt die Warnung durch das Projekt zu ändern Properties> Build> Errors and warnings> Suppress warningsvon 1591 eingeben
Fügen Sie die XML-Dokumentations-Tags hinzu ( GhostDoc kann dafür sehr praktisch sein).
Unterdrücken Sie die Warnung über Compileroptionen
Deaktivieren Sie die „XML - Dokumentationsdatei“ Checkbox in Projekt Properties> Build>Output
Fügen Sie #pragma warning disable 1591oben in der jeweiligen Datei und #pragma warning restore 1591unten hinzu

Gorgsenegger
quelle

178

Bitte, bitte benutze GhostDoc nicht. Wenn ein Kommentar aus dem Methodennamen abgeleitet werden kann, kann er von einem Menschen besser abgeleitet werden. Dies addiert den Wert Null. In dieser Zeit sollten Sie sich besser zu einer bekannten Methode beglückwünschen.

JRoughan

24

Ich muss nicht zustimmen, GhostDoc hilft mir, schnell die erforderliche Liste von Parametern und ein Rückgabetag hinzuzufügen (wenn die Methode nicht ungültig ist). Ich benutze und mag es, und ich kenne einige andere Leute, die es auch tun. Es ist jedoch richtig, dass die Beschreibung in der Zusammenfassung möglicherweise bearbeitet werden muss, dies gilt jedoch für die meisten Automatismen in solchen Fällen.

Gorgsenegger

32

Wenn nur Platzhalter hinzugefügt würden, wäre dies eine nette kleine Zeitersparnis, aber die Anzahl der Codebasen, die Entwickler gesehen haben, die den generierten Text verlassen, lässt uns glauben, dass wir nicht kollektiv ausgereift genug sind, um ihn zu verwenden. Kommentare sind eine (oft notwendige) Krücke für Code, der sich nicht selbst dokumentiert. Durch das Anbieten von Verknüpfungen hat dieses Tool einen negativen Nettovorteil für den Code der Welt.

JRoughan

25

@JRoughan: Ich stimme vollkommen zu. Das Schlimmste ist, wenn Sie endlich die Zeit finden, Ihren Code ordnungsgemäß zu dokumentieren, können Sie mit diesen Tools nicht feststellen, wie gründlich Ihre tatsächliche Dokumentationsabdeckung ist. Jedes Tool, das die Dokumentationsabdeckung berechnet, liest immer 100%. Sie müssen also buchstäblich die geistig anstrengende Aufgabe durchlaufen, jeden XML-Kommentar zu lesen und zu bewerten, ob es ausreicht, den Code zu dokumentieren. Nachdem ich das bei einem großen Projekt gemacht habe, kann ich Ihnen sagen, dass es überhaupt keinen Spaß macht. Bitte Leute! Verwenden Sie diese Tools zur automatischen Dokumentation nicht!

HiredMind

36

@ Gorgsenegger: In diesem Fall nicht. Es ist nicht das Werkzeug, das fehlerhaft ist, es ist das gesamte Konzept. VS2012 fügt standardisierten XML-Kommentaren Methoden- / Parameter-Stubs hinzu, wenn Sie dies wünschen. Das Hinzufügen von Kommentaren, die einfach längere Versionen der Methodennamen sind, und das Aufrufen der Dokumentation ist jedoch nur eine visuelle Unordnung.

HiredMind

74

Deaktivieren Sie die Warnung: Wechseln Sie zu den Projekteigenschaften (Klicken Sie mit der rechten Maustaste auf Ihr Projekt und wählen Sie im Kontextmenü die Option Eigenschaften.) Wechseln Sie zur Registerkarte Erstellen

Fügen Sie 1591 zum Textfeld Warnungen unterdrücken hinzu

Rao Adnan
quelle

4

Funktioniert wie ein Zauber mit durch Kommas getrennten Listen: "S125, CS1591, S1172". Nach einem Bau verschwanden die Warings.

AFD

9

Vielen Dank, dass Sie die Frage beantwortet und nicht darüber gesprochen haben, ob Sie die Warnungen unterdrücken sollen oder nicht!

Dal

31

Sie können die .csprojDatei Ihres Projekts auch so ändern , dass sie ein <noWarn>1591</noWarn>Tag in die erste enthält <PropertyGroup>. Ursprünglich aus Alexandru Bucurs Artikel hier

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

DotNetPadawan
quelle

3

Dies sollte die Antwort für aktuelle Tage sein.

Edgar Salazar

3

Einverstanden. Die meisten Antworten funktionieren nicht mit anderen Editoren wie Visual Studio Code.

Krzysztof Czelusniak

9

Gehen Sie in die Projekteigenschaften und deaktivieren Sie die Option XML-Dokument generieren.

Neu kompilieren und die Warnungen sollten verschwinden.

Chris
quelle

2

Dies ist ein guter Ansatz, solange Sie die XML-Dokumente nicht generieren müssen und es Ihnen nichts ausmacht, dass die XML-Kommentare nicht validiert werden.

Keith

1

Dies funktioniert nicht, wenn Sie die Warnungen von Dateien behalten möchten, die nicht automatisch generiert werden. Das Entfernen aller Warnungen, nur um eine Teilmenge von Warnungen loszuwerden, scheint mir etwas übertrieben. Außerdem ist es in den meisten Unternehmen üblich, XML-Kommentare in allen Dateien zu erstellen, die keinen automatisch generierten Code enthalten. Außerdem hat der Benutzer nach einer Lösung gefragt, bei der die XML-Kommentarfunktion nicht einfach entfernt wird, sodass die Frage nicht beantwortet wird.

SubliemeSiem

4

Dies wäre ein Kommentar gewesen, aber ich konnte ihn nicht dazu bringen, die Einschränkung zu erfüllen:

Ich würde sie gerne nur für die Importe Reference.cs und WebService deaktivieren. Eigentlich benutze ich ein Makro, um es für eine Datei zu tun. Öffnen Sie einfach die Datei und führen Sie dieses Makro aus (getestet in 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

Gibt es wirklich keine Möglichkeit, dies automatisch zu tun? Sie müssten dies jedes Mal wiederholen, wenn der automatisch generierte Code die Datei überschreibt.

Kjellski
quelle

2

Ich denke, diese Warnung sollte nicht für automatisch generierte Inhalte angezeigt werden. Möglicherweise müssen Sie die entsprechende Einstellung in den Projekteigenschaften überprüfen.

Gorgsenegger

1

Nein, alles wird angezeigt, indem nur XML-Kommentar-Warnungen aktiviert werden. Und es gibt keine solche Option, um es nur für automatisch generierten Code zu deaktivieren. Daher wird der Code abgeschnitten, wenn Sie den Code neu generieren müssen.

Kjellski

Unter Projekteigenschaften Code Analysisgibt es eine Option Supress results from generated code. Ein Makro nach jeder Code-Regeneration erneut ausführen zu müssen, ist IMO keine wirkliche Lösung. Wenn die obige Option für Sie nicht funktioniert, kann der Codegenerator möglicherweise so angepasst werden, dass stattdessen automatisch die Pragma-Direktive hinzugefügt wird.

Laoujin

@ Laoujin danke für deinen Kommentar, aber wie ich schon erwähnt habe, mag ich diese Lösung auch nicht. Ich kann keinen Grund für die Ablehnung sehen. Ich habe die von Ihnen erwähnte Einstellung ohne Erfolg verwendet. Gibt es eine Chance, dass Sie Ihre Lösung für WebService-Importe ausprobieren?

Kjellski

Visual Studio Deaktivieren fehlender XML-Kommentar Warnung

Antworten: