Visual Studio wyłącza brakujące komentarze XML Ostrzeżenie

198

Mam projekt z ponad 500 Missing XML Commentostrzeżeniami. Wiem, że mogę usunąć funkcję komentarzy XML lub wkleić puste fragmenty komentarzy wszędzie, ale wolę ogólne rozwiązanie, w którym mogę wprowadzić jedną zmianę, która wyłącza wszystkie ostrzeżenia tego typu.

To co teraz robię, to wkładanie

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

lub 

#pragma warning disable 1591

był ciekawy, czy to możliwe.

visual-studio-2010 xml-comments Nivid Dholakia
źródło
3
Jakie jest aktualne pytanie? Czy chcesz poznać inny sposób wyłączenia ostrzeżeń generowanych w przypadku braku komentarzy XML? We właściwościach projektu zmień zakładkę „Kompiluj” i odznacz „Plik dokumentacji XML”. Sugeruję jednak, aby nie ukrywać ostrzeżeń, ale dodać brakującą dokumentację.
Gorgsenegger,
To jest absolutnie poprawne, ale byłem ciekawy, jak rozwiązać ten problem z jednego miejsca, ponieważ byłem nowy.
Nivid Dholakia,
Te pokrewne pytania mogą pomóc: stackoverflow.com/questions/11444631/… stackoverflow.com/questions/3630282/…
Mightymuke
1
Ostrzeżenie pojawia się tylko dla elementów, które są widoczne dla innych zespołów. Często ludzie tworzą klasy (i interfejsy, wyliczenia itp.) publicBez uzasadnionego powodu. W takim przypadku łatwym (i moim zdaniem dobrym) rozwiązaniem jest po prostu usunięcie słowa public(lub zastąpienie go zbędnym internalsłowem kluczowym, w zależności od preferowanego stylu) z najbardziej zewnętrznego typu zamykającego. Następnie wszystkie ostrzeżenia CS1591 dotyczące tego typu i jego członków znikają. Oczywiście nadal będziesz musiał zachować niektóre typy public. Ale w takim przypadku to sprawiedliwe, że musisz odpowiednio udokumentować ich części publiczne.
Jeppe Stig Nielsen

Odpowiedzi:

318

Jak zasugerowano powyżej, ogólnie nie uważam, że te ostrzeżenia powinny być ignorowane (pomijane). Podsumowując, sposoby obejścia tego ostrzeżenia to:

  • Tłumić ostrzeżenie poprzez zmianę projektu Properties> Build> Errors and warnings> Suppress warningswpisując 1591
  • Dodaj tagi dokumentacji XML ( GhostDoc może być do tego całkiem przydatny)
  • Pomiń ostrzeżenie za pomocą opcji kompilatora
  • Usuń zaznaczenie „plik dokumentacji XML” checkbox w projekcie Properties> Build>Output
  • Dodaj #pragma warning disable 1591na górze odpowiedniego pliku i #pragma warning restore 1591na dole
Gorgsenegger
źródło
178
Proszę, nie używaj GhostDoc. Jeśli komentarz można wywnioskować z nazwy metody, może być on lepiej wywnioskowany przez człowieka. Dodaje to wartość zerową. Lepiej spędzić ten czas, gratulując sobie dobrze znanej metody.
JRoughan
24
Muszę się nie zgodzić, GhostDoc pomaga mi szybko dodać wymaganą listę parametrów i tag zwrotny (jeśli metoda nie jest nieważna). Używam i lubię to i znam całkiem sporo innych ludzi, którzy też to robią. Prawdą jest jednak, że opis w podsumowaniu może wymagać edycji, ale w większości przypadków ma to znaczenie.
Gorgsenegger
32
Gdyby tylko dodał symbole zastępcze, byłoby to miło zaoszczędzić trochę czasu, ale liczba baz kodu, które widziałem, w których programiści zostawiają wygenerowany tekst, sprawia, że ​​uważamy, że nie jesteśmy wystarczająco dojrzali, aby z niego korzystać. Komentarze są (często niezbędną) kulą dla kodu, który nie jest samodokumentujący, a oferując skróty, narzędzie to ma ujemną korzyść netto w kodzie światów.
JRoughan
25
@JRoughan: Całkowicie się zgadzam. Najgorsze jest to, że kiedy wreszcie znajdziesz czas na odpowiednie udokumentowanie swojego kodu, narzędzia te uniemożliwiają określenie, jak dokładny jest twój prawdziwy zakres dokumentacji. Każde narzędzie, które oblicza pokrycie dokumentacji, zawsze będzie czytało 100%. Musisz dosłownie przejść przez wyczerpujące umysłowo zadanie czytania każdego komentarza XML i oceny, czy wystarczy udokumentować kod. Po wykonaniu dużego projektu mogę powiedzieć, że wcale nie jest fajnie. Proszę ludzi! Nie używaj tych narzędzi do automatycznej dokumentacji!
HiredMind
36
@Gorgsenegger: Nie w tym przypadku. To nie jest wadliwe narzędzie, to cała koncepcja. VS2012 dodaje kody pośredniczące metody / parametru do znormalizowanych komentarzy XML, jeśli tego właśnie chcesz. Ale dodawanie komentarzy, które są po prostu dłuższymi wersjami nazw metod i nazywanie ich dokumentacją, to tylko wizualny bałagan.
HiredMind
74

Wyłącz ostrzeżenie: Przejdź do właściwości projektu (kliknij prawym przyciskiem myszy swój projekt i wybierz Właściwości z menu kontekstowego) Przejdź do zakładki Kompilacja wprowadź opis zdjęcia tutaj

Dodaj 1591 do pola tekstowego Pomiń ostrzeżenia wprowadź opis zdjęcia tutaj

Rao Adnan
źródło
4
Działa jak urok z listami oddzielonymi przecinkami: „S125, CS1591, S1172”. Po kompilacji wojny zniknęły.
AFD
9
Dziękujemy za udzielenie odpowiedzi na pytanie i nie wykładanie, czy zignorować ostrzeżenia!
Dal
31

Możesz także zmodyfikować .csprojplik swojego projektu, aby dodać <noWarn>1591</noWarn>znacznik do pierwszego <PropertyGroup>. Pochodzi z artykułu Alexandru Bucur tutaj

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    ...
    <NoWarn>1591</NoWarn>
  </PropertyGroup>
  ...
</Project>
DotNetPadawan
źródło
3
To powinno być answear na bieżące dni.
Edgar Salazar
3
Zgoda. Większość odpowiedzi nie działa z innymi edytorami, takimi jak Visual Studio Code.
Krzysztof Czelusniak
9

Przejdź do właściwości projektu i odznacz opcję generowania dokumentu XML.

Odznacz plik dokumentacji XML

Ponownie skompiluj, a ostrzeżenia powinny zniknąć.

Chris
źródło
2
Jest to dobre podejście, o ile nie trzeba generować dokumentów XML i nie ma nic przeciwko temu, że komentarze XML nie zostaną sprawdzone.
Keith,
1
To nie działa, jeśli chcesz zachować ostrzeżenia z plików, które nie są generowane automatycznie. Usunięcie wszystkich ostrzeżeń tylko w celu pozbycia się podzbioru ostrzeżeń wydaje mi się nieco przesadne. Poza tym w większości firm powszechną praktyką jest tworzenie komentarzy XML we wszystkich plikach, które nie zawierają automatycznie generowanego kodu. Ponadto użytkownik poprosił o rozwiązanie, które nie usuwa po prostu funkcji komentowania XML, więc nie odpowiada na pytanie.
SubliemeSiem,
4

Byłby to komentarz, ale nie mogłem go dopasować do ograniczenia:

Chciałbym je wyłączyć tylko dla importowania plików Reference.cs i WebService. Właściwie używam makra, aby zrobić to dla pliku. Wystarczy otworzyć plik i uruchomić to makro (Testowane w 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

Naprawdę nie ma sposobu, aby to zrobić automatycznie? Będziesz musiał powtórzyć to za każdym razem, gdy automatycznie wygenerowany kod zastąpi plik.

Kjellski
źródło
2
Myślę, że to ostrzeżenie nie powinno się wyświetlać w przypadku treści generowanych automatycznie, być może będziesz musiał sprawdzić odpowiednie ustawienie we właściwościach projektu.
Gorgsenegger,
1
Nie, wszystko to widać po włączeniu ostrzeżeń o komentarzach XML. I nie ma takiej opcji, aby wyłączyć ją tylko dla kodu generowanego automatycznie. Dlatego snipowany, gdy potrzebujesz zregenerować kod.
Kjellski
W obszarze właściwości projektu Code Analysisistnieje opcja Supress results from generated code. Ponowne uruchamianie makra po każdej regeneracji kodu nie jest tak naprawdę rozwiązaniem IMO. Jeśli powyższa opcja nie działa, być może generator kodu można dostosować tak, aby zamiast tego automatycznie dodawał dyrektywę pragma?
Laoujin
@Laoujin dziękuję za komentarz, ale jak już wspomniałem, nie podoba mi się również to rozwiązanie. Nie widzę powodu, by głosować negatywnie. Użyłem ustawienia, o którym wspominasz, bez powodzenia. Czy jest szansa, że ​​wypróbujesz swoje rozwiązanie do importu WebService?
Kjellski