Brak komentarza XML dla publicznie widocznego typu lub członka

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

Jak to rozwiązać?

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)

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.

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

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ń.

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).

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..

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.

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

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

#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

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

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

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ń.

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

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()
{
}