Как документировать унаследованные элементы?

Question

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

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

Answer 1

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

• Документ абстрактного метода, просто говоря, что он реализует метод интерфейса и связывается с ним. Нет ничего лишнего, чтобы сказать об этом, и дублирование комментария нарушает принцип DRY (Do not Repeat Yourself): вы должны были бы запомнить любые изменения в нем в и местах. (Конечно, в случае абстрактного метода, который не реализует метод интерфейса, документировать его таким же образом, что вы бы задокументировать метод интерфейса.)

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

Answer 2

замечание на part of post по Eric Anastas

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

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