Отсутствует комментарий XML для публично видимого типа или члена


381

Я получаю это предупреждение: «Отсутствует комментарий XML для публично видимого типа или члена».

Как это решить?


8
Я вижу это тоже в Visual Studio. Кто-нибудь знает, из какого программного обеспечения исходит это предупреждение? Стиль Полицейский? Fx Cop? Анализ кода? Как я могу выключить его?
Полковник Паник

Ответы:


668

5 вариантов:

  • Заполните комментарии к документации (отлично, но отнимает много времени)
  • Отключить генерацию комментариев (в свойствах проекта)
  • Отключите предупреждение в свойствах проекта (в «Свойствах проекта» перейдите в «Свойства проекта» -> «Сборка»> «Ошибки и предупреждения» (раздел), «Подавить предупреждения» (текстовое поле), добавьте 1591 (список через запятую)). По умолчанию это изменит Активную Конфигурацию, рассмотрите возможность изменения конфигурации на Все.
  • Используйте #pragma warning disable 1591для отключения предупреждения только для некоторых битов кода (и #pragma warning restore 1591после)
  • Игнорировать предупреждения (плохая идея - вы пропустите новые «настоящие» предупреждения)

5
@Jon, нашел решение: если вы получите это предупреждение для составного кода с частичным классом, ищите «другую половину» частичного класса, который не генерируется. Если вы добавите туда XML-комментарий, предупреждение для сгенерированного кода будет отклонено. У меня было это предупреждение для класса App в файле App.gics, сгенерированном из кода XAML в проекте WP7. Чтобы решить эту проблему, мне пришлось добавить комментарий XML в файл App.xaml.cs (который не генерируется).
Марсель W

@MarcelW: Ах, так это не для созданных участников? Или они все равно внутренние? Это имело бы смысл ...
Джон Скит

7
Кроме того , если вы получаете это предупреждение от Service Reference Auto-генерируемый код, вы можете щелкнуть правой кнопкой мыши по ссылке службы, выберите «Настроить ссылку на службу ...», а затем изменить «уровень доступа для сгенерированных классов» в Internal.
Ли Гриссом

9
Если вы отключаете предупреждения, как объясняет @NickJ, убедитесь, что вы меняете их для всех конфигураций, а не только для debug \ release.
Авиталь

5
Вы также можете добавить его в качестве атрибута класса, если хотите подавить код для всего класса: [System.Diagnostics.CodeAnalysis.SuppressMessage ("Microsoft.Usage", "CS1591")]
cr1pto,

92

Добавьте XML-комментарии к публично видимым типам и членам, конечно же :)

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

Вам нужны эти <summary>комментарии типа для всех участников - они также отображаются во всплывающем меню intellisense.

Причина вы получите это предупреждение, потому что вы настроили свой проект для вывода документации файла XML (в настройках проекта). Это полезно для библиотек классов (сборок .dll), что означает, что пользователи вашего .dll получают документацию intellisense для вашего API прямо в Visual Studio.

Я рекомендую вам получить копию надстройки GhostDoc Visual Studio. Упрощает документирование.


8
+1 за упоминание GhostDoc. Никогда не знал об этом, это, безусловно, облегчает документирование.
Вивелин

7
+1 за указание причины предупреждения. Нашел параметр в разделе «Сборка» в свойствах проекта (VS 2008) и выключил его в одном проекте из десяти, которые он загадочным образом проверял без всякой уважительной причины.
Чак Уилбур

30
-1 За рекомендацию GhostDoc- самый глупый аддон, который я когда-либо видел. Генерирует документацию. Теперь остановитесь на секунду, чтобы подумать об этом. Вы хотите, чтобы ваш код был более понятным, поэтому вы используете инструмент, который генерирует документацию исключительно на основе имени метода и типов аргументов. Имеет ли это для вас смысл? Пользователь может увидеть имя и типы аргументов, добавить комментарий к DateTime date- Дата действительно не помогает.
Гдорон поддерживает Монику

4
@gdoron, возможно, вам это и не пришло в голову, но вы можете редактировать документацию, создаваемую GhostDoc, что сэкономит вам много времени по сравнению с написанием всей документации с нуля.
Джоэл МакБет,

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

41

Подавить предупреждения для комментариев XML

(не моя работа, но я нашел ее полезной, поэтому я включил статью и ссылку)

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

Здесь я покажу вам, как вы можете подавить предупреждения для комментариев XML после сборки Visual Studio.

Фон

Если вы отметили отметку «Файл документации XML» в настройках проекта Visual Studio, будет создан файл XML, содержащий все комментарии XML. Кроме того, вы получите много предупреждений в файлах, созданных дизайнером, из-за отсутствующих или неправильных комментариев XML. Хотя иногда предупреждения помогают нам улучшать и стабилизировать наш код, получение сотен предупреждений о комментариях XML - это просто боль. Предупреждения

Отсутствует комментарий XML для публично видимого типа или члена… Комментарий XML для… имеет тег param для «…», но нет параметра с таким именем. Параметр «…» не имеет соответствующего тега param в комментарии XML для «…» (но другие параметры делают) решение

Вы можете подавить каждое предупреждение в Visual Studio.

  • Щелкните правой кнопкой мыши проект Visual Studio / Свойства / Вкладка «Сборка»

  • Вставьте следующие номера предупреждений в «Подавить предупреждения»: 1591,1572,1571,1573,1587,1570


6
Мне нужно было только добавить 1591, чтобы подавить предупреждения комментариев XML.
Брайан Бем

Спасибо за список кодов! Я начал собирать их один за другим, и в 3-м билде с предупреждениями я пришел к мысли, что мне нужно взять его откуда-то как есть :)
sarh

Что - то не прав, 1591 также удаляет «Устаревшие» предупреждения, но MS указывает , что это о комментариях только msdn.microsoft.com/en-us/library/zk18c1w9.aspx
Pawel Cioch

Я также проверил на MS все 1572,1571,1573,1587,1570, и я бы не стал их устанавливать, это более конкретные ошибки, допустим, вы установили /// <summary>, а затем вы допустили ошибку в параметрах, вы должен получить предупреждение
Pawel Cioch

27

Есть еще один способ подавления этих сообщений без необходимости изменения кода или блоков прагмы. Использование Visual Studio - перейдите в свойства проекта> «Сборка»> «Ошибки и предупреждения»> «Подавить предупреждения» - добавьте 1591 к списку кодов предупреждений.

введите описание изображения здесь


Это, безусловно, лучший, самый простой и самый быстрый для реализации ответ, который я когда-либо видел для этой проблемы. Это повторение другого ответа выше, но этот гораздо более визуально наглядный, давая быстрый мгновенный ответ. Большое спасибо.
Дэвид Кови

Лучший ответ здесь. Не позволяет мне разбрасывать мою кодовую базу #pragma warning disableповсюду, что просто раздражает.
RoadRunner - MSFT

23

Вставьте комментарий XML. ;-)

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

На первый взгляд это может показаться шуткой, но на самом деле это может быть полезно. Для меня оказалось полезным подумать о том, что делают методы, даже для частных методов (если, конечно, это не тривиально).


5
Я всегда комментирую методы, но для свойств (которые являются технически методами, но обычно имеют тривиальные реализации и самоочевидные имена) я предпочитаю избегать скуки и повторения добавления лишних XML-комментариев.
Питер Глюк

15

Это связано с тем, что в свойствах вашего проекта указан файл документации XML, а ваш метод / класс является общедоступным и не имеет документации.
Вы также можете :

  1. Отключить XML документацию:

    Щелкните правой кнопкой мыши по вашему проекту -> Свойства -> вкладка «Сборка» -> снимите флажок «Файл документации XML».

  2. Сядьте и напишите документацию самостоятельно!

Резюме XML-документации выглядит следующим образом:

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

Спасибо вам. Я думаю, что этот путь - лучший правильный способ отключить предупреждение
Рамиль Алиев

8

Я хотел бы добавить что-то к ответам, перечисленным здесь:

Как указал Исак, документация XML полезна для библиотек классов, так как она обеспечивает интеллектуальный смысл для любого потребителя в Visual Studio. Следовательно, простое и правильное решение - просто отключить документацию для любого проекта верхнего уровня (такого как пользовательский интерфейс и т. Д.), Который не будет реализован вне собственного проекта.

Кроме того, я хотел бы отметить, что предупреждение выражается только для публично видимых участников. Таким образом, если вы настроите свою библиотеку классов так, чтобы она отображала только то, что ей нужно, вы можете обойтись без документирования privateи internalчленов.


8

Я знаю, что это действительно старая тема, но это первый ответ в Google, поэтому я решил добавить эту информацию:

это происходит только в том случае, если для уровня предупреждения установлено значение 4 в разделе «Свойства проекта» -> «Построить» , Если вам действительно не нужно столько информации, вы можете установить ее на 3, и вы избавитесь от этих предупреждений. Конечно, изменение уровня предупреждения влияет не только на комментарии, поэтому, если вы не уверены в том, чего вам не хватает, обратитесь к документации:
https://msdn.microsoft.com/en-us/library/thxezb7y.aspx


7

В вашем решении, после того, как вы отметите опцию создания файла XML-документа, оно начнет проверять ваших открытых членов на наличие XMLDoc, а если нет, вы получите предупреждение для каждого элемента. если вы действительно не хотите выпускать свою DLL, а также вам не нужна документация, перейдите к своему решению, соберите раздел и отключите его, иначе, если вам это нужно, заполните их, и если они не важны Свойства и поля, просто превзойти их с помощью инструкции перед компилятором, #pragma warning disable 1591 вы также можете восстановить предупреждение: #pragma warning restore 1591

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

#pragma warning disable 1591 и если вам нужно восстановить его, используйте: #pragma warning restore 1591

Вот пример:

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

Обратите внимание, что директива прагмы начинается в начале строки


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

Установка уровня предупреждения на 2 подавляет эти сообщения. Не знаю, является ли это лучшим решением, поскольку оно также подавляет полезные предупреждения.


Я полагаю, что вместо того, чтобы выбирать это, отключение документации XML снижает риски.
Аджай Арадхья

2

Ответ Джона Скита отлично подходит для тех случаев, когда вы строите с помощью VisualStudio. Однако, если вы собираете sln через командную строку (в моем случае это была Ant), вы можете обнаружить, что msbuild игнорирует запросы подавления sln.

Добавление этого в командную строку msbuild решило проблему для меня:

/p:NoWarn=1591

1

Файл > Правка > Просмотр проекта (нажмите)

Внизу раскрывающегося лука (нажмите « Открыть» / «Текущая работа» > « Свойства» ), открылась страница свойств проекта в «Build» в «Output». Снимите флажок « Документация XML» .

Восстановите и никаких предупреждений.


Не забудьте также проверить все ваши конфигурации сборки. Я снял флажок для Debug, но не для Release, и был очень смущен.
MattM

1
Это решение не является решением в случае документации по WebAPI. Вам нужно включить эту опцию, но подавить предупреждения.
Павел Cioch

1

Вам необходимо добавить /// Комментарий для участника, для которого отображается предупреждение.

см. ниже код

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

Отображается предупреждение «Отсутствует комментарий XML» для публично видимого типа или члена «.EventLogger ()».

Я добавил комментарий для участника и предупреждение исчезло.

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

-5

Я получил это сообщение после того, как прикрепил атрибут к методу

[webMethod]
public void DoSomething()
{
}

Но правильный путь был такой:

[webMethod()] // Note the Parentheses 
public void DoSomething()
{
}
Используя наш сайт, вы подтверждаете, что прочитали и поняли нашу Политику в отношении файлов cookie и Политику конфиденциальности.
Licensed under cc by-sa 3.0 with attribution required.