Правило StyleCop SA1600 требует, чтобы каждый член типа имел собственный заголовок документации. Я считаю это вполне разумным, и мне нравится это правило. Но предположим, что у нас есть следующая иерархия:
/// <summary>
/// Documentation for interface ISomeModule.
/// </summary>
interface ISomeModule
{
/// <summary>
/// Documentation for DoA.
/// </summary>
void DoA();
/// <summary>
/// Documentation for DoB.
/// </summary>
void DoB();
}
/// <summary>
/// Documentation for StandardModule.
/// </summary>
class StandardModule : ISomeModule
{
private readonly SomeCoolType _value;
/// <summary>
/// Documentation for constructor.
/// </summary>
public StandardModule(SomeCoolType value)
{
_value = value;
}
// SA1600 violation here!
public void DoA()
{
// realisation of DoA().
}
// SA1600 violation here!
public void DoB()
{
// realisation of DoB().
}
/// <summary>
/// Documentation for MyOwnDoC.
/// </summary>
public void MyOwnDoC()
{
// realisation of MyOwnDoC().
}
}
Здесь я полностью документировал элементы интерфейса DoA() и DoB(), мы знаем, что эти методы делают именно из документации интерфейса. VS Intellisence тоже это знает, и мы можем видеть описание методов, наведя курсор мыши на эти методы даже в классе StandardModule. Поэтому нет необходимости копировать документацию из интерфейса в производный класс. Но StyleCop требует этого. Зачем? Кто-нибудь знает?
Если мы попытаемся решить эту проблему, мы можем пойти 4 различными способами:
1. Скопируйте документацию из интерфейса. Проблема в том, что если мы скопируем документацию, мы столкнемся с проблемой обновления документации во всех производных классах, если изменится поведение интерфейса.
2. Подавить сообщение с помощью SuppressMessageAttribute. Ну, предположим, мы говорим: "Хорошо, я могу использовать SuppressMessageAttribute", чтобы подавить это нарушение, с которым я не согласен. И я добавляю класс StandardModule с SuppressMessageAttribute для правила SA1600. Но теперь StyleCop перестает проверять заголовки документации в классе StandardModule. Я не хочу этого, потому что у нас есть конструктор и некоторые другие методы.
3. Разделите класс на регионы, Мы можем разделить класс StandardModule на 2 области и использовать подавление сообщений только в той части, которая реализует интерфейс ISomeModule. И я думаю, что все части должны быть помещены в один файл. Мне нравится этот подход больше всего (по пути № 4), но теперь мы имеем дело с несколькими частями одного класса.
4. Измените правило SA1600. Возможно ли выполнить мою собственную реализацию правила SA1600, чтобы он учитывал, были ли элементы класса задокументированы в базовом классе или в интерфейсе? (здесь я не спрашиваю, можем ли мы написать собственное правило для StyleCop, я знаю, что мы можем, но я имею в виду, может ли механизм StyleCop проверять, пришли ли некоторые члены из интерфейса или базового класса).
Каков наиболее предпочтительный способ решения проблемы SA1600 при реализации интерфейса?
Предстоящая версия StyleCop 4.4.1 должна поддерживать тег inheritdoc. Если вы хотите использовать инструмент создания документации, который поддерживает этот тег (например: Sandcastle или FiXml), у вас может быть рабочее решение, которое будет касаться обеих ваших проблем.
Мне никогда не приходило в голову, что это будет проблемой, потому что я всегда рассматривал документацию объявления интерфейса как нечто отличное от документации реализации этот интерфейс.
Возможно, я ошибаюсь, но я рад узнать.
Мой фактический ответ на ваш вопрос: 1) Копировать Перевести документацию из интерфейса.