Brak komentarza XML dla publicznie widocznego typu lub członka


381

Otrzymuję ostrzeżenie: „Brak komentarza XML dla publicznie widocznego typu lub członka”.

Jak to rozwiązać?


8
Widzę to również w Visual Studio. Czy ktoś wie, z jakiego oprogramowania pochodzi to ostrzeżenie? Stylowy glina? Fx Cop? Analiza kodu? Jak mogę to wyłączyć?
Pułkownik Panic

Odpowiedzi:


668

5 opcji:

  • Uzupełnij komentarze do dokumentacji (świetne, ale czasochłonne)
  • Wyłącz generowanie komentarzy (we właściwościach projektu)
  • Wyłącz ostrzeżenie we właściwościach projektu (w „Właściwościach projektu” przejdź do Właściwości projektu -> Kompilacja> „Błędy i ostrzeżenia” (sekcja), Pomiń ostrzeżenia (pole tekstowe), dodaj 1591 (lista oddzielona przecinkami)). Domyślnie zmieni konfigurację aktywną, rozważ zmianę konfiguracji na Wszystkie.
  • Użyj, #pragma warning disable 1591aby wyłączyć ostrzeżenie tylko dla niektórych fragmentów kodu (i #pragma warning restore 1591później)
  • Zignoruj ​​ostrzeżenia (zły pomysł - przegapisz nowe „prawdziwe” ostrzeżenia)

5
@Jon, znalazłem rozwiązanie: Jeśli pojawi się to ostrzeżenie dla kodu gereated z klasą częściową, poszukaj „drugiej połowy” klasy częściowej, która nie została wygenerowana. Jeśli dodasz tam komentarz XML, ostrzeżenie dla wygenerowanego kodu zniknie. Miałem to ostrzeżenie dla klasy App w pliku App.gics wygenerowanym z kodu XAML w projekcie WP7. Aby rozwiązać ten problem, musiałem dodać komentarz XML do pliku App.xaml.cs (który nie jest generowany).
Marcel W

@MarcelW: Ach, więc to nie jest dla wygenerowanych członków? A może wszystkie są wewnętrzne? To miałoby sens ...
Jon Skeet

7
Ponadto, jeśli otrzymujesz to ostrzeżenie z kodu wygenerowanego automatycznie odwołania do usługi , możesz kliknąć prawym przyciskiem myszy odwołanie do usługi, wybrać „Konfiguruj odwołanie do usługi ...”, a następnie zmienić „Poziom dostępu dla wygenerowanych klas” na Wewnętrzny.
Lee Grissom,

9
Jeśli wyłączasz ostrzeżenia, jak wyjaśnia @NickJ, upewnij się, że zmieniasz je dla wszystkich konfiguracji, a nie tylko dla debugowania \ wydania.
Avital

5
Możesz również dodać to jako atrybut klasy, jeśli chcesz wyłączyć kod dla całej klasy: [System.Diagnostics.CodeAnalysis.SuppressMessage („Microsoft.Usage”, „CS1591”)]
cr1pto

92

Dodaj komentarze XML do publicznie widocznych typów i członków oczywiście :)

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

Potrzebujesz tego <summary>typu komentarzy do wszystkich członków - pojawiają się one również w wyskakującym menu inteligencji.

Powód dostać to ostrzeżenie jest bo masz ustawione projektu dokumentacji wyjście pliku xml (w ustawieniach projektu). Jest to przydatne w przypadku bibliotek klas (zestawów .dll), co oznacza, że ​​użytkownicy twojego .dll otrzymują dokumentację Intellisense dla twojego API właśnie tam w Visual Studio.

Polecam ci kopię GhostDoc Visual Studio AddIn .. Znacznie ułatwia dokumentowanie.


8
+1 za wzmiankę o GhostDoc. Nigdy o tym nie wiedziałem, z pewnością ułatwia dokumentowanie.
Vivelin

7
+1 za podanie przyczyny ostrzeżenia. Znalazłem ustawienie w obszarze Kompiluj we właściwościach projektu (VS 2008) i wyłączyłem je w jednym z dziesięciu projektów, który w tajemniczy sposób sprawdził to bez uzasadnionego powodu.
Chuck Wilbur,

30
-1 Za polecenie GhostDoc- najgłupszy AddOn, jaki kiedykolwiek widziałem. Generuje dokumentację. Zatrzymaj się na chwilę, aby się nad tym zastanowić. Chcesz, aby Twój kod był bardziej zrozumiały, więc korzystasz z narzędzia, które generuje dokumentację wyłącznie na podstawie nazwy metody i typów argumentów. Czy to ma dla ciebie sens? Użytkownik może zobaczyć nazwę i typy argumentów, dodać komentarz do DateTime date- Data naprawdę nie pomaga.
gdoron wspiera Monikę

4
@gdoron, może nie przyszło ci to do głowy, ale możesz edytować dokumentację generowaną przez GhostDoc, co pozwoli ci zaoszczędzić dużo czasu w porównaniu z pisaniem całej dokumentacji od zera.
Joel McBeth

3
GhostDoc nie tylko zgaduje, jakie powinny być komentarze - choć przez większość czasu jest dość blisko i wystarczy edytować kilka słów zamiast wpisywać całość - i jeśli dokumentujesz poprawnie (a ty prawdopodobnie nie są), istnieje szablon dla większości rzeczy, jak należy je sformułować (dla właściwości, konstruktorów itp.), a GhostDoc umieszcza je w - jeszcze fajniejsze: Jeśli jesteś w klasie podrzędnej, może wypełnij dokumentację dokumentacją z klasy podstawowej jako szablon do pracy, zamiast kopiować ją ręcznie - wprowadza wyjątek blurbs itp.
BrainSlugs83

41

Pomiń ostrzeżenia o komentarzach XML

(nie moja praca, ale uznałem ją za przydatną, dlatego zamieściłem artykuł i link)

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

Tutaj pokażę ci, jak można ukryć ostrzeżenia dotyczące komentarzy XML po kompilacji Visual Studio.

tło

Jeśli zaznaczyłeś znacznik „Plik dokumentacji XML” w ustawieniach projektu Visual Studio, tworzony jest plik XML zawierający wszystkie komentarze XML. Dodatkowo otrzymasz wiele ostrzeżeń również w plikach generowanych przez projektantów, z powodu brakujących lub niewłaściwych komentarzy XML. Chociaż czasami ostrzeżenia pomagają nam ulepszać i stabilizować nasz kod, otrzymywanie setek ostrzeżeń o komentarzach XML to tylko ból. Ostrzeżenia

Brakuje komentarza XML dla publicznie widocznego typu lub elementu… Komentarz XML… ma znacznik param dla „…”, ale nie ma parametru o tej nazwie Parametr „…” nie ma pasującego znacznika param w komentarzu XML dla „…” (ale inne parametry) Rozwiązanie

Możesz wyłączyć każde ostrzeżenie w Visual Studio.

  • Kliknij prawym przyciskiem myszy projekt Visual Studio / kartę Właściwości / kompilację

  • Wstaw „Numbers ostrzeżenia” w następujący sposób: 1591,1572,1571,1573,1587,1570


6
Musiałem tylko dodać 1591, aby wyłączyć ostrzeżenia o komentarzach Xml.
Brian Behm,

Dzięki za listę kodów! Zacząłem zbierać je jeden po drugim i na 3. kompilacji z ostrzeżeniami doszedłem do wniosku, że muszę wziąć to
skądinąd

Coś jest nie tak, 1591 usuwa również ostrzeżenia „Przestarzałe”, ale MS wskazuje, że chodzi tylko o komentarze msdn.microsoft.com/en-us/library/zk18c1w9.aspx
Paweł Cioch

Sprawdziłem także na MS wszystkie 1572,1571,1573,1587,1570, i nie ustawiłbym ich, są to bardziej konkretne błędy, powiedzmy, że ustawiłeś /// <podsumowanie> a potem popełnisz błąd w params, ty powinien otrzymać ostrzeżenie
Paweł Cioch,

26

Istnieje inny sposób tłumienia tych komunikatów bez potrzeby zmiany kodu lub bloków pragma. Korzystanie z programu Visual Studio - Przejdź do właściwości projektu> Kompilacja> Błędy i ostrzeżenia> Wyłącz ostrzeżenia - dołącz 1591 do listy kodów ostrzeżeń.

wprowadź opis zdjęcia tutaj


Jest to zdecydowanie najlepsza, najłatwiejsza i najszybsza do wdrożenia odpowiedź, jaką do tej pory widziałem dla tego problemu. Jest to powtórzenie kolejnej odpowiedzi powyżej, ale ta jest znacznie bardziej opisowa i daje szybką odpowiedź natychmiastową. Dziękuję Ci bardzo.
David Covey

Najlepsza odpowiedź tutaj. Zapobiega rozrzucaniu mojej bazy kodu #pragma warning disablewszędzie, co jest po prostu denerwujące.
RoadRunner - MSFT

23

Wstaw komentarz XML. ;-)

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

Na pierwszy rzut oka może się to wydawać żartem, ale może być przydatne. Dla mnie pomocne okazało się zastanowienie się, jakie metody robią nawet w przypadku metod prywatnych (chyba, że ​​naprawdę trywialne).


5
Zawsze komentuję metody, ale w przypadku właściwości (które są metodami tenicznymi, ale zazwyczaj mają trywialne implementacje i oczywiste nazwy) wolę unikać nudy i powtarzania dodawania zbędnych komentarzy XML.
Peter Gluck,

15

Wynika to z faktu, że plik właściwości XML został określony we właściwościach projektu, a metoda / klasa jest publiczna i brakuje w niej dokumentacji.
Możesz albo :

  1. Wyłącz dokumentację XML:

    Kliknij prawym przyciskiem myszy swój projekt -> Właściwości -> zakładka „Kompiluj” -> odznacz Plik dokumentacji XML.

  2. Usiądź i napisz dokumentację!

Podsumowanie dokumentacji XML wygląda następująco:

/// <summary>
/// Description of the class/method/variable
/// </summary>
..declaration goes here..

Dzięki Ci. Myślę, że ten sposób jest najlepszym prawidłowym sposobem wyłączenia ostrzeżenia
Ramil Aliyev

8

Chciałem dodać coś do odpowiedzi tutaj wymienionych:

Jak wskazał Isak, dokumentacja XML jest przydatna dla bibliotek klas, ponieważ zapewnia inteligencję każdemu konsumentowi w Visual Studio. Dlatego łatwym i poprawnym rozwiązaniem jest po prostu wyłączenie dokumentacji dla dowolnego projektu najwyższego poziomu (takiego jak interfejs użytkownika itp.), Który nie będzie wdrażany poza własnym projektem.

Dodatkowo chciałem zauważyć, że ostrzeżenie dotyczy tylko publicznie widocznych członków. Jeśli więc skonfigurujesz bibliotekę klas, aby ujawniała tylko to, czego potrzebuje, możesz to zrobić bez dokumentacji privatei internalczłonków.


8

Wiem, że to naprawdę stary wątek, ale jest to pierwsza odpowiedź w Google, więc pomyślałem, że dodam trochę informacji:

To zachowanie występuje tylko wtedy, gdy poziom ostrzeżenia jest ustawiony na 4 w „Właściwościach projektu” -> „Kompilacja” . Jeśli nie potrzebujesz tak dużo informacji, możesz ustawić ją na 3, a pozbysz się tych ostrzeżeń. Oczywiście zmiana poziomu ostrzeżenia ma wpływ nie tylko na komentarze, więc jeśli nie masz pewności, co zaginiesz, zapoznaj się z dokumentacją:
https://msdn.microsoft.com/en-us/library/thxezb7y.aspx


7

W swoim rozwiązaniu, gdy zaznaczysz opcję generowania pliku dokumentu XML, zaczniesz sprawdzać swoich publicznych członków, czy posiadających XMLDoc, jeśli nie, otrzymasz ostrzeżenie dla każdego elementu. jeśli tak naprawdę nie chcesz zwolnić swojej biblioteki DLL, a także nie potrzebujesz dokumentacji, przejdź do rozwiązania, skompiluj sekcję i wyłącz ją, w przeciwnym razie, jeśli jest to potrzebne, wypełnij je, a jeśli są nieistotne właściwości i pola, wystarczy je wyprzedzić instrukcją prekompilatora #pragma warning disable 1591 , można także przywrócić ostrzeżenie: #pragma warning restore 1591

użycie pragma: w dowolnym miejscu w kodzie przed miejscem, w którym pojawia się ostrzeżenie kompilatora dla ... (dla pliku, umieść go w nagłówku i nie musisz go włączać ponownie, dla pojedynczego zawinięcia klasy lub zawinięcia metody metodę, albo ... nie musisz jej owijać, możesz ją wywołać i przywrócić swobodnie (zacznij od początku pliku i zakończ w metodzie)), napisz ten kod:

#pragma warning disable 1591 a jeśli chcesz go przywrócić, użyj: #pragma warning restore 1591

Oto przykład:

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; }
    }
}

Zauważ, że dyrektywa pragma zaczyna się na początku linii


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

2

Ustawienie poziomu ostrzeżenia na 2 pomija te komunikaty. Nie wiem, czy jest to najlepsze rozwiązanie, ponieważ eliminuje także przydatne ostrzeżenia.


Myślę, że zamiast decydować się na to, wyłączenie dokumentacji xml zmniejsza ryzyko.
Ajay Aradhya

2

Odpowiedź Jona Skeeta działa świetnie, gdy budujesz za pomocą VisualStudio. Jednakże, jeśli budujesz sln za pomocą wiersza poleceń (w moim przypadku było to przez Ant), może się okazać, że msbuild ignoruje żądania wyłączenia sln.

Dodanie tego do wiersza polecenia msbuild rozwiązało problem:

/p:NoWarn=1591

1

Plik > Edytuj > Wyświetl projekt (kliknij)

Dół rozwijanego łuku (kliknij Otwórz / Bieżąca praca > Właściwości ), otworzył stronę właściwości projektu w „Kompilacji” w „Wyjściu”. Pole wyboru „Odznacz” dokumentację XML .

Odbuduj i żadnych ostrzeżeń.


Pamiętaj również o sprawdzeniu wszystkich konfiguracji kompilacji. Odznacziłem to dla Debugowania, ale nie dla Release i byłem bardzo zdezorientowany.
MattM

1
To rozwiązanie nie jest rozwiązaniem w przypadku dokumentacji WebAPI. Musisz włączyć tę opcję, ale pomiń ostrzeżenia.
Paweł Cioch

1

Musisz dodać /// komentarz do członka, dla którego wyświetlane jest ostrzeżenie.

patrz poniższy kod

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

Wyświetla ostrzeżenie Brakujący komentarz XML dla publicznie widocznego typu lub elementu „.EventLogger ()”

Dodałem komentarz do członka i ostrzeżenie zniknęło.

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

-5

Dostałem ten komunikat po dołączeniu atrybutu do metody

[webMethod]
public void DoSomething()
{
}

Ale poprawny sposób był następujący:

[webMethod()] // Note the Parentheses 
public void DoSomething()
{
}
Korzystając z naszej strony potwierdzasz, że przeczytałeś(-aś) i rozumiesz nasze zasady używania plików cookie i zasady ochrony prywatności.
Licensed under cc by-sa 3.0 with attribution required.