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

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

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

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


xml c# documentation code-documentation
person Mike Post    schedule 19.03.2010    source источник

Ответы (4)


arrow_upward
3
arrow_downward

Как насчет того, чтобы вообще не предоставлять 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. Внутри вы можете включить визуальную студию, чтобы «видеть» эти расширенные конструкции. На странице EditorBrowsableAttribute рассказывается, как:

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

person Jordão    schedule 18.04.2011

arrow_upward
5
arrow_downward

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

person John Saunders    schedule 19.03.2010
comment
Увы, я имею дело с большим количеством кода, поэтому это нецелесообразно. - person Mike Post; 19.03.2010
comment
@Mike Post Сохранение общедоступного API отдельно от частного API должно было быть вашей главной задачей с первого дня, если это не так, то вам предстоит много рефакторинга. Для этого нет быстрого решения, и то, что предлагает Джон, на самом деле очень аккуратно, не знал, что вы можете открывать внутренние методы для других сборок friend. - person John Leidegren; 18.04.2011

arrow_upward
3
arrow_downward

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

Не могли бы вы вместо этого прокомментировать эти методы простым комментарием ‹summary›Not for external use.‹/summary›?

person MattDavey    schedule 18.04.2011

arrow_upward
2
arrow_downward

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

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

#pragma warning disable 1591
public class B{
    //...
}
person Iain Sproat    schedule 18.04.2011