Как я должен документировать унаследованных членов?

Question

Учтите, что у меня сложная структура классов, в которой многие элементы наследуются от других элементов. У меня может быть метод GetStuff(string stuffName, int count) определяется в интерфейсе, который наследуется другим интерфейсом, который затем реализуется абстрактно абстрактным классом, который затем реализуется явно в конкретном классе и т. д. и т. д.

Как я должен обращаться с унаследованными членами, такими как GetStuff() при документировании моего кода с XML-комментариями, которые будут использоваться с такими инструментами, как Doxygen или Sandcastle? Кажется неправильным просто копировать и вставлять одно и то же описание на каждом уровне. Должен ли я рассматривать другую аудиторию на уровне интерфейса по сравнению с конкретным уровнем класса? Например, документация для GetStuff() в интерфейсе может учитывать людей, реализующих интерфейс, тогда как документация на конкретном уровне может вместо этого рассматривать людей, которые будут использовать класс?

Answer 1

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

• Документируйте абстрактный метод, просто сказав, что он реализует интерфейсный метод и связавшись с ним. В этом нет ничего лишнего, и дублирование комментария нарушает принцип "СУХОЙ" ("Не повторяйся"): вам нужно помнить, чтобы вносить в него изменения в обоих местах. (Конечно, в случае абстрактного метода, который не реализует интерфейсный метод, документируйте его так же, как документальный метод интерфейса.)

• Задокументируйте конкретную реализацию, сказав, что она реализует метод интерфейса и / или переопределяет абстрактный член. При желании добавьте информацию о его реализации, если она имеет отношение к вызывающей стороне - например, его характеристики производительности или ситуации, в которых он может бросить, и т. Д.

Answer 2

Замечание по части сообщения Eric Anastas

Кажется неправильным просто копировать и вставлять одно и то же описание на каждом уровне.

Я могу представить, что неправильно просто копировать. Однако возможно позволить doxygen скопировать его для вас, а затем изменить то, что вы хотели бы изменить для этой реализации / области. Для получения дополнительной информации вы можете посмотреть описание @copydoc.