Visual Studio Отключение предупреждения об отсутствующих комментариях XML

199

У меня есть проект с более чем 500 Missing XML Commentпредупреждениями. Я знаю, что могу удалить функцию XML Comment или вставить пустые фрагменты комментариев везде, но я бы предпочел универсальное решение, в котором я могу внести одно изменение, которое отключит все предупреждения этого типа.

То, что я делаю только сейчас, это положить

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

или 

#pragma warning disable 1591

было просто любопытно, если бы это было возможно.

visual-studio-2010 xml-comments Нивид дхолакия
источник
3
Какой актуальный вопрос? Хотели бы вы знать другой способ отключить предупреждения, которые генерируются, когда отсутствуют комментарии XML? В свойствах проекта перейдите на вкладку «Сборка» и снимите флажок «Файл документации XML». Однако я бы предложил не подавлять предупреждения, а добавить недостающую документацию.
Горгзенеггер
Это абсолютно правильно, но было просто любопытно, как, если мы сможем решить это из одного места, как я был новичком в этом.
Нивид Дхолакия
Эти связанные вопросы могут помочь: stackoverflow.com/questions/11444631/… stackoverflow.com/questions/3630282/…
Mightymuke
1
Предупреждение появляется только для элементов, видимых для других сборок. Часто люди делают классы (и интерфейсы, перечисления и т. Д.) publicБез уважительной причины. В этом случае простое (и, на мой взгляд, хорошее) решение - просто удалить слово public(или заменить его избыточным internalключевым словом, в зависимости от предпочтительного стиля) из внешнего внешнего типа. Тогда все предупреждения CS1591 об этом типе и его членах исчезают. Конечно, вам все равно придется сохранить некоторые типы public. Но в этом случае справедливо, что вы требуете надлежащего документирования их публичных частей.
Джеппе Стиг Нильсен

Ответы:

318

Как предложено выше, в целом я не думаю, что эти предупреждения следует игнорировать (подавлять). Подводя итог, можно сказать, что способы предупреждения будут следующими:

  • Подавить предупреждение путем изменения проекта Properties> Build> Errors and warnings> Suppress warningsвведя 1591
  • Добавьте теги документации XML (для этого может пригодиться GhostDoc )
  • Подавить предупреждение с помощью параметров компилятора
  • Снимают «Файл документации XML» флажок в проекте Properties> Build>Output
  • Добавьте #pragma warning disable 1591вверху соответствующего файла и #pragma warning restore 1591внизу
Gorgsenegger
источник
179
Пожалуйста, пожалуйста, не используйте GhostDoc. Если комментарий может быть выведен из имени метода, он может быть выведен лучше человеком. Это добавляет нулевое значение. Это время лучше потратить на поздравления с хорошо названным методом.
JRoughan
24
Я должен не согласиться, GhostDoc помогает мне быстро добавить необходимый список параметров и возвращаемый тег (если метод не является пустым). Я использую и люблю это, и я знаю довольно много других людей, которые также делают. Это правда, однако, что описание в резюме может потребовать некоторого редактирования, но в таких случаях это учитывает большинство автоматизмов.
Gorgsenegger
32
Если бы все, что он сделал, это добавил местозаполнители, это было бы неплохо сэкономить время, но количество кодовых баз, которые я видел, когда разработчики оставляют сгенерированный текст, заставляет нас думать, что мы просто недостаточно зрелы, чтобы использовать его. Комментарии являются (часто необходимым) опорой для кода, который не является самодокументированным, и, предлагая ярлыки, этот инструмент имеет отрицательное преимущество в коде мира.
JRoughan
25
@JRoughan: я полностью согласен. Хуже всего то, что когда вы наконец-то нашли время для правильного документирования своего кода, эти инструменты не дают возможности определить, насколько тщательно вы охватили всю документацию. Любой инструмент, который рассчитывает охват документации, всегда будет читать 100%. Таким образом, вы буквально должны пройти умственно утомительную задачу - прочитать каждый XML-комментарий и оценить, достаточно ли этого для документирования кода. Сделав это на большом проекте, могу вам сказать, это совсем не весело. Пожалуйста, люди! Не используйте эти инструменты автоматического документирования!
HiredMind
36
@Gorgsenegger: не в этом случае. Это не инструмент, который имеет недостатки, а вся концепция. VS2012 добавляет заглушки методов / параметров в стандартные комментарии XML, если вы этого хотите. Но добавление комментариев, которые являются просто более длинными версиями имен методов, и вызов их документации - это просто визуальный беспорядок.
HiredMind
74

Отключить предупреждение: перейдите в свойства проекта (щелкните правой кнопкой мыши свой проект и выберите «Свойства» в контекстном меню). Перейдите на вкладку «Сборка». введите описание изображения здесь

Добавьте 1591 в текстовое поле Подавить предупреждения введите описание изображения здесь

Рао Аднан
источник
5
Работает как брелок со списками через запятую: «S125, CS1591, S1172». После сборки исчезли угри.
AFD
10
Спасибо, что ответили на вопрос, а не читали лекции о том, следует ли подавлять предупреждения!
Даль
31

Вы также можете изменить .csprojфайл вашего проекта, чтобы включить <noWarn>1591</noWarn>тег внутри первого <PropertyGroup>. Первоначально из статьи Александра Букура Здесь

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    ...
    <NoWarn>1591</NoWarn>
  </PropertyGroup>
  ...
</Project>
DotNetPadawan
источник
3
Это должен быть ответ на текущий день.
Эдгар Салазар
3
Согласовано. Большинство ответов не работают с другими редакторами, такими как Visual Studio Code.
Кшиштоф Челюсняк
9

Зайдите в свойства проекта и снимите флажок сгенерировать документ XML.

Снимите отметку с XML-файла документации

Перекомпилируйте и предупреждения должны исчезнуть.

Крис
источник
2
Это хороший подход, если вам не нужно генерировать документы XML, и вы не возражаете, что комментарии XML не будут проверены.
Кит
1
Это не работает, если вы хотите сохранить предупреждения от файлов, которые не генерируются автоматически. Удаление всех предупреждений только для того, чтобы избавиться от подмножества предупреждений, кажется мне немного излишним. Кроме того, в большинстве компаний обычной практикой является создание XML-комментариев во всех файлах, которые не содержат автоматически сгенерированный код. Кроме того, пользователь попросил решение, которое не просто удаляет функцию комментариев XML, поэтому это не отвечает на вопрос.
SubliemeSiem
4

Это был бы комментарий, но я не мог заставить его соответствовать ограничению:

Я хотел бы отключить их только для импорта Reference.cs и WebService. На самом деле я использую макрос, чтобы сделать это для файла. Просто откройте файл и выполните этот макрос (протестировано в 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

Неужели нет способа сделать это автоматически? Вам придется повторять это каждый раз, когда автоматически сгенерированный код переопределяет файл.

Kjellski
источник
2
Я думаю, что это предупреждение не должно отображаться для автоматически сгенерированного контента, возможно, вам придется проверить соответствующий параметр в свойствах проекта.
Горгзенеггер
1
Нет, все это показано, просто включив предупреждения XML-Comment. И нет такой возможности отключить его только для автоматически сгенерированного кода. Для этого отсекается, когда вам нужно восстановить код.
Kjellski
В свойствах проекта Code Analysisесть опция Supress results from generated code. Необходимость повторного запуска макроса после каждой регенерации кода на самом деле не является решением IMO. Если вышеуказанная опция не работает для вас, возможно, генератор кода можно настроить так, чтобы он автоматически добавлял директиву pragma?
Лаужин
@Laoujin спасибо за ваш комментарий, но, как я уже говорил, мне не нравится это решение. Я не вижу причин для понижения, я безуспешно использовал упомянутые вами настройки. Есть ли шанс попробовать ваше решение для импорта WebService?
Kjellski