Fehlender XML-Kommentar für öffentlich sichtbaren Typ oder Mitglied

381

Ich erhalte die folgende Warnung: "Fehlender XML-Kommentar für öffentlich sichtbaren Typ oder Mitglied".

Wie kann man das lösen?

J.-BC
quelle
8
Ich sehe das auch in Visual Studio. Weiß jemand, von welcher Software diese Warnung stammt? Style Cop? Fx Cop? Code-Analyse? Wie kann ich es ausschalten?
Colonel Panic

Antworten:

668

5 Optionen:

  • Füllen Sie die Dokumentationskommentare aus (großartig, aber zeitaufwändig).
  • Deaktivieren Sie die Kommentargenerierung (in den Projekteigenschaften).
  • Deaktivieren Sie die Warnung in den Projekteigenschaften (gehen Sie in 'Projekteigenschaften' zu Projekteigenschaften -> Erstellen> "Fehler und Warnungen" (Abschnitt), Warnungen unterdrücken (Textfeld), fügen Sie 1591 hinzu (durch Kommas getrennte Liste)). Standardmäßig wird die aktive Konfiguration geändert. Ziehen Sie in Betracht, die Konfiguration in Alle zu ändern.
  • Verwenden Sie #pragma warning disable 1591diese Option, um die Warnung nur für einige Codebits (und #pragma warning restore 1591danach) zu deaktivieren.
  • Ignorieren Sie die Warnungen (schlechte Idee - Sie werden neue "echte" Warnungen verpassen)
Jon Skeet
quelle
5
@ Jon, fand die Lösung: Wenn Sie diese Warnung für gereanten Code mit einer Teilklasse erhalten, suchen Sie nach der "anderen Hälfte" der Teilklasse, die nicht generiert wird. Wenn Sie dort einen XML-Kommentar hinzufügen, wird die Warnung für den generierten Code ausgeblendet. Ich hatte diese Warnung für die App-Klasse in der App.gics-Datei, die aus dem XAML-Code in einem WP7-Projekt generiert wurde. Um das Problem zu beheben, musste ich der Datei App.xaml.cs einen XML-Kommentar hinzufügen (der nicht generiert wird).
Marcel W
@MarcelW: Ah, also nicht für die generierten Mitglieder? Oder sind sie alle alle intern? Das würde Sinn machen ...
Jon Skeet
7
Wenn Sie diese Warnung von einer automatisch generierten Dienstreferenz erhalten , können Sie mit der rechten Maustaste auf die Dienstreferenz klicken, "Dienstreferenz konfigurieren ..." auswählen und dann "Zugriffsebene für generierte Klassen" in "Intern" ändern.
Lee Grissom
9
Wenn Sie die Warnungen als @NickJ explaind deaktivieren, stellen Sie sicher, dass Sie sie für alle Konfigurationen und nicht nur für debug \ release ändern.
Avital
5
Sie können dies auch als Klassenattribut hinzufügen, wenn Sie Code für eine gesamte Klasse unterdrücken möchten: [System.Diagnostics.CodeAnalysis.SuppressMessage ("Microsoft.Usage", "CS1591")]
cr1pto
92

Fügen Sie den öffentlich sichtbaren Typen und Mitgliedern natürlich XML-Kommentare hinzu :)

///<Summary>
/// Gets the answer
///</Summary>
public int MyMethod()
{
   return 42;
}

Sie benötigen diese <summary>Typkommentare für alle Mitglieder - diese werden auch im Intellisense-Popup-Menü angezeigt.

Das Grund , warum Sie diese Warnung erhalten, ist, dass Sie Ihr Projekt so eingestellt haben, dass es die XML-Dokumentationsdatei ausgibt (in den Projekteinstellungen). Dies ist nützlich für Klassenbibliotheken (DLL-Assemblys). Dies bedeutet, dass Benutzer Ihrer DLL direkt in Visual Studio eine Intellisense-Dokumentation für Ihre API erhalten.

Ich empfehle Ihnen, sich eine Kopie des GhostDoc Visual Studio AddIn zu besorgen. Erleichtert die Dokumentation erheblich.

Isak Savo
quelle
8
+1 für die Erwähnung von GhostDoc. Ich wusste nie davon, es erleichtert sicherlich die Dokumentation.
Vivelin
7
+1 für die Angabe des Grundes für die Warnung. Fand die Einstellung unter In den Projekteigenschaften erstellen (VS 2008) und schaltete sie bei einem von zehn Projekten aus, die auf mysteriöse Weise ohne guten Grund überprüft wurden.
Chuck Wilbur
30
-1 Für die Empfehlung GhostDoc- das dümmste AddOn, das ich je gesehen habe. Es generiert Dokumentation. Halten Sie jetzt eine Sekunde inne, um darüber nachzudenken. Sie möchten, dass Ihr Code verständlicher wird, und verwenden daher ein Tool, das die Dokumentation ausschließlich auf der Grundlage des Methodennamens und der Argumenttypen generiert. Macht es für dich Sinn? Der Benutzer kann den Namen und die Typen der Argumente sehen und einen Kommentar hinzufügen DateTime date- Das Datum hilft wirklich nicht.
Gdoron unterstützt Monica
4
@gdoron, es ist Ihnen vielleicht nicht in den Sinn gekommen, aber Sie können die von GhostDoc generierte Dokumentation bearbeiten, wodurch Sie viel Zeit sparen, anstatt die gesamte Dokumentation von Grund auf neu zu schreiben.
Joel McBeth
3
GhostDoc kann nicht nur raten, wie die Kommentare lauten sollen - obwohl es meistens ziemlich eng ist und Sie nur ein paar Wörter bearbeiten müssen, anstatt das Ganze abzutippen - und ob Sie richtig dokumentieren (und Sie wahrscheinlich nicht), es gibt eine Vorlage für die meisten Dinge, wie sie formuliert werden müssen (für Eigenschaften, Konstruktoren usw.), und GhostDoc fügt diese ein - noch cooler: Wenn Sie in einer Kinderklasse sind, kann es Füllen Sie die Dokumentation mit der aus der Basisklasse als Vorlage aus, mit der Sie arbeiten möchten, anstatt sie von Hand zu kopieren - sie fügt die Ausnahme-Klappentexte usw. ein.
BrainSlugs83
41

Unterdrücken Sie Warnungen für XML-Kommentare

(nicht meine Arbeit, aber ich fand sie nützlich, also habe ich den Artikel und den Link eingefügt)

http://bernhardelbl.wordpress.com/2009/02/23/suppress-warnings-for-xml-comments/

Hier zeige ich Ihnen, wie Sie Warnungen für XML-Kommentare nach einem Visual Studio-Build unterdrücken können.

Hintergrund

Wenn Sie die Markierung "XML-Dokumentationsdatei" in den Visual Studio-Projekteinstellungen aktiviert haben, wird eine XML-Datei mit allen XML-Kommentaren erstellt. Darüber hinaus erhalten Sie aufgrund fehlender oder falscher XML-Kommentare auch in vom Designer generierten Dateien viele Warnungen. Während manchmal Warnungen uns helfen, unseren Code zu verbessern und zu stabilisieren, ist es nur ein Schmerz, Hunderte von XML-Kommentarwarnungen zu erhalten. Warnungen

Fehlender XML-Kommentar für öffentlich sichtbaren Typ oder Mitglied… XML-Kommentar zu… hat ein Parameter-Tag für '…', aber es gibt keinen Parameter mit diesem Namen. Parameter '…' hat kein passendes Parameter-Tag im XML-Kommentar für '…' (aber andere Parameter tun) Lösung

Sie können jede Warnung in Visual Studio unterdrücken.

  • Klicken Sie mit der rechten Maustaste auf die Registerkarte Visual Studio-Projekt / Eigenschaften / Erstellen

  • Fügen Sie die folgenden Warnnummern in die "Warnungen unterdrücken" ein: 1591,1572,1571,1573,1587,1570

Sprotty
quelle
6
Ich musste nur 1591 hinzufügen, um die XML-Kommentarwarnungen zu unterdrücken.
Brian Behm
Danke für die Codeliste! Ich habe angefangen, sie
einzeln
Etwas stimmt nicht, 1591 entfernt auch "veraltete" Warnungen, aber MS gibt an, dass es sich nur um Kommentare handelt. Msdn.microsoft.com/en-us/library/zk18c1w9.aspx
Pawel Cioch
Ich habe auch alle 1572,1571,1573,1587,1570 auf MS überprüft, und ich würde sie nicht festlegen, es handelt sich um spezifischere Fehler. Nehmen wir an, Sie haben /// <Zusammenfassung> festgelegt, und dann machen Sie einen Fehler in den Parametern sollte Warnung bekommen
Pawel Cioch
26

Es gibt eine andere Möglichkeit, diese Nachrichten zu unterdrücken, ohne dass Codeänderungen oder Pragmablöcke erforderlich sind. Verwenden von Visual Studio - Gehen Sie zu Projekteigenschaften> Erstellen> Fehler und Warnungen> Warnungen unterdrücken - fügen Sie 1591 an die Liste der Warncodes an.

Geben Sie hier die Bildbeschreibung ein

ekhanna
quelle
Dies ist bei weitem die beste, einfachste und am schnellsten zu implementierende Antwort, die ich bisher für dieses Problem gesehen habe. Es ist eine Wiederholung einer anderen Antwort oben, aber diese ist visuell viel aussagekräftiger und gibt eine schnelle sofortige Antwort. Vielen Dank.
David Covey
Beste Antwort hier. Verhindert, dass ich meine Codebasis #pragma warning disableüberall verstreue , was nur ärgerlich ist.
RoadRunner - MSFT
23

Fügen Sie einen XML-Kommentar ein. ;-);

/// <summary>
/// Describe your member here.
/// </summary>
public string Something
{
    get;
    set;
}

Dies mag auf den ersten Blick wie ein Witz erscheinen, kann aber tatsächlich nützlich sein. Für mich hat es sich als hilfreich erwiesen, darüber nachzudenken, was Methoden auch für private Methoden tun (es sei denn, es ist natürlich wirklich trivial).

Matthias Meid
quelle
5
Ich kommentiere immer Methoden, aber für Eigenschaften (die tehnisch Methoden sind, aber normalerweise triviale Implementierungen und selbstverständliche Namen haben) ziehe ich es vor, die Langeweile und Wiederholung des Hinzufügens überflüssiger XML-Kommentare zu vermeiden.
Peter Gluck
15

Dies liegt daran, dass in Ihren Projekteigenschaften eine XML-Dokumentationsdatei angegeben wurde und Ihre Methode / Klasse öffentlich ist und keine Dokumentation enthält.
Du kannst entweder :

  1. XML-Dokumentation deaktivieren:

    Klicken Sie mit der rechten Maustaste auf Ihr Projekt -> Eigenschaften -> Registerkarte "Erstellen" -> Deaktivieren Sie die Option XML-Dokumentationsdatei.

  2. Setzen Sie sich und schreiben Sie die Dokumentation selbst!

Die Zusammenfassung der XML-Dokumentation sieht folgendermaßen aus:

/// <summary>
/// Description of the class/method/variable
/// </summary>
..declaration goes here..
Ajay Aradhya
quelle
Danke. Ich denke, dieser Weg ist der beste richtige Weg, um die Warnung zu deaktivieren
Ramil Aliyev
8

Ich wollte den hier aufgeführten Antworten etwas hinzufügen:

Wie Isak betonte, ist die XML-Dokumentation für Klassenbibliotheken nützlich, da sie jedem Benutzer in Visual Studio Intellisense bietet. Eine einfache und korrekte Lösung besteht daher darin, die Dokumentation für jedes Projekt der obersten Ebene (wie z. B. Benutzeroberfläche usw.) zu deaktivieren, das nicht außerhalb des eigenen Projekts implementiert werden soll.

Außerdem wollte ich darauf hinweisen, dass die Warnung nur für öffentlich sichtbare Mitglieder gilt. Wenn Sie also Ihre Klassenbibliothek so einrichten, dass nur das angezeigt wird, was sie benötigt, können Sie ohne Dokumentation privateund internalMitglieder auskommen .

Mike Guthrie
quelle
8

Ich weiß, dass dies ein wirklich alter Thread ist, aber es ist die erste Antwort auf Google, daher dachte ich, ich würde diese Informationen hinzufügen:

Dieses Verhalten tritt nur auf, wenn die Warnstufe unter "Projekteigenschaften" -> "Erstellen" auf 4 gesetzt ist. . Wenn Sie nicht wirklich so viele Informationen benötigen, können Sie diese auf 3 setzen und diese Warnungen entfernen. Das Ändern der Warnstufe wirkt sich natürlich nicht nur auf Kommentare aus. Wenn Sie sich nicht sicher sind, was Sie vermissen, lesen Sie bitte die Dokumentation:
https://msdn.microsoft.com/en-us/library/thxezb7y.aspx

Marius Agur
quelle
7

Wenn Sie in Ihrer Lösung die Option zum Generieren einer XML-Dokumentdatei aktiviert haben, werden Ihre öffentlichen Mitglieder auf XMLDoc überprüft. Wenn dies nicht der Fall ist, erhalten Sie für jedes Element eine Warnung. Wenn Sie Ihre DLL nicht wirklich freigeben möchten und dann auch keine Dokumentationen benötigen, gehen Sie zu Ihrer Lösung, erstellen Sie einen Abschnitt und deaktivieren Sie ihn. Wenn Sie ihn benötigen, füllen Sie ihn aus, und wenn er unwichtig ist Eigenschaften und Felder, übertreffen Sie sie einfach mit einer Pre-Compiler-Anweisung. #pragma warning disable 1591 Sie können auch die Warnung wiederherstellen: #pragma warning restore 1591

Pragma-Verwendung: Jeder Ort im Code vor dem Ort, an dem Sie eine Compiler-Warnung für ... erhalten (für eine Datei in den Header einfügen, und Sie müssen sie nicht erneut aktivieren, für einen einzelnen Klassenumbruch um eine Klasse oder für einen Methodenumbruch eine Methode, oder ... Sie müssen sie entweder nicht umschließen, Sie können sie aufrufen und beiläufig wiederherstellen (beginnen am Anfang der Datei und enden in einer Methode)), schreiben Sie diesen Code:

#pragma warning disable 1591 und falls Sie es wiederherstellen müssen, verwenden Sie: #pragma warning restore 1591

Hier ein Beispiel:

using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using MongoDB.Bson;
using MongoDB.Bson.Serialization.Attributes;
using RealEstate.Entity.Models.Base;

namespace RealEstate.Models.Base
{
    public class CityVM
    {

#pragma warning disable 1591

        [Required]
        public string Id { get; set; }

        [Required]
        public string Name { get; set; }

        public List<LanguageBasedName> LanguageBasedNames { get; set; }

        [Required]
        public string CountryId { get; set; }

#pragma warning restore 1591

        /// <summary>
        /// Some countries do not have neither a State, nor a Province
        /// </summary>
        public string StateOrProvinceId { get; set; }
    }
}

Beachten Sie, dass die Pragma-Direktive am Zeilenanfang beginnt

deadManN
quelle
2
#pragma warning disable 1591
#pragma warning disable 1591
#pragma warning disable 1572
#pragma warning disable 1571
#pragma warning disable 1573
#pragma warning disable 1587
#pragma warning disable 1570
Petar
quelle
2

Wenn Sie die Warnstufe auf 2 setzen, werden diese Meldungen unterdrückt. Ich weiß nicht, ob es die beste Lösung ist, da es auch nützliche Warnungen unterdrückt.

danpop
quelle
Anstatt sich dafür zu entscheiden, reduziert das Deaktivieren der XML-Dokumentation die Risiken.
Ajay Aradhya
2

Die Antwort von Jon Skeet eignet sich hervorragend, wenn Sie mit VisualStudio erstellen. Wenn Sie die SLN jedoch über die Befehlszeile erstellen (in meinem Fall über Ant), werden Sie möglicherweise feststellen, dass msbuild die SLN-Unterdrückungsanforderungen ignoriert.

Das Hinzufügen zur msbuild-Befehlszeile löste das Problem für mich:

/p:NoWarn=1591
Bill Tarbell
quelle
1

Datei > Bearbeiten > Projekt anzeigen (klicken)

Unten im Dropdown-Bogen (klicken Sie auf Öffnen / Aktuelle Arbeit > Eigenschaften ) wurde die Seite mit den Projekteigenschaften unter "Erstellen" unter "Ausgabe" geöffnet. Kontrollkästchen " XML-Dokumentation deaktivieren" .

Wiederaufbau und keine Warnungen.

Tom
quelle
Überprüfen Sie auch alle Build-Konfigurationen. Ich hatte es für Debug, aber nicht für Release deaktiviert und war sehr verwirrt.
MattM
1
Diese Lösung ist keine Lösung für den Fall der WebAPI-Dokumentation. Sie müssen diese Option aktivieren, aber die Warnungen unterdrücken.
Pawel Cioch
1

Sie müssen /// Kommentar für das Mitglied hinzufügen, für das eine Warnung angezeigt wird.

siehe unten Code

public EventLogger()
{
    LogFile = string.Format("{0}{1}", LogFilePath, FileName);
}

Es wird eine Warnung angezeigt. Fehlender XML-Kommentar für öffentlich sichtbaren Typ oder Mitglied '.EventLogger ()'

Ich habe einen Kommentar für das Mitglied hinzugefügt und die Warnung ist weg.

///<Summary>
/// To write a log <Anycomment as per your code>
///</Summary>
public EventLogger()
{
    LogFile = string.Format("{0}{1}", LogFilePath, FileName);
}
Sujeet Singh
quelle
-5

Ich habe diese Nachricht erhalten, nachdem ich ein Attribut an eine Methode angehängt habe

[webMethod]
public void DoSomething()
{
}

Aber der richtige Weg war folgender:

[webMethod()] // Note the Parentheses 
public void DoSomething()
{
}
Coyolero
quelle