Выборочно подавить комментарии XML-кода в C #?

Question

Мы поставляем ряд сборок внешним клиентам, но не все публичные API официально поддерживаются. Например, из-за неоптимальных вариантов проектирования иногда необходимо публично представить тип из сборки, чтобы остальная часть нашего кода работала, но мы не хотим, чтобы клиенты использовали этот тип. Одной из частей сообщения об отсутствии поддержки не является предоставление какого-либо интеллектуального смысла в форме комментариев XML.

Есть ли способ выборочно подавлять комментарии XML? Я ищу что-то другое, кроме игнорирования предупреждения 1591, поскольку это проблема долгосрочного обслуживания.

Пример: у меня есть сборка с открытыми классами A и B. Официально поддерживается A и должна иметь документацию XML. B не предназначен для наружного применения и не должен документироваться. Я мог бы включить документацию XML и затем отключить предупреждение 1591. Но когда я позже добавлю официально поддерживаемый класс C, я хочу, чтобы компилятор сказал мне, что я облажался и не смог добавить документацию XML. Этого не произошло бы, если бы я подавил 1591 на уровне проекта. Я полагаю, я мог бы использовать #pragma во всех классах, но, похоже, должен быть лучший способ сделать это.

Answer 1

Создайте такие методы internal и добавьте атрибут [assembly: InternalsVisibleTo("AssemblyName")] в сборку, открывающую их.

Answer 2

Как насчет вообще не предоставлять intellisense?

///<summary>A documentation</summary> 
public class A { }

///<summary>B documentation. This class is not supported...</summary> 
[EditorBrowsable(EditorBrowsableState.Advanced)]
public class B { }

///<summary>C documentation</summary> 
public class C { }

Таким образом, вы все равно можете документировать неподдерживаемые классы (внутренние пользователи также важны!), И ваши внешние пользователи не видят их в intellisense. Внутри вы можете включить visual studio, чтобы «увидеть» эти сложные конструкции. Страница для EditorBrowsableAttribute рассказывает нам, как:

В Visual C # вы можете управлять появлением расширенных свойств в IntelliSense и окне свойств с помощью параметра «Скрыть расширенных членов» в разделе «Инструменты | Варианты | Текстовый редактор | C #. Соответствующий EditorBrowsableState имеет значение Advanced.

Answer 3

Одна часть сообщения об отсутствии поддержки не предусматривает какой-либо intellisense в виде XML комментарии.

Не могли бы вы вместо этого прокомментировать эти методы простым

Не для внешнего использования.

комментарий?

Answer 4

Попробуйте использовать директиву #pragma для включения или отключения определенных предупреждений .

///<summary>some documentation</summary>
public class A{
    //...
}

#pragma warning disable 1591
public class B{
    //...
}