С# XML Комментарии: Сколько ссылок <see.../"> в комментариях XML полезно?

В нашей компании мы пишем чрезмерные комментарии Xml. Типичный метод должен быть документирован следующим образом:

/// <summary>
/// Determines whether this <see cref="IScheduler"/> contains a specific <see cref="ISchedule"/>.
/// </summary>
/// <param name="schedule">The <see cref="ISchedule"/> to locate in this <see cref="IScheduler"/>.</param>
/// <returns>
/// Returns <see langword="true"/> if <paramref name="schedule"/> is found in this <see cref="IScheduler"/>; otherwise, <see langword="false"/>.
/// </returns>
bool Contains(ISchedule schedule);

/// <summary>
/// Removes and <see cref="IDisposable.Dispose"/>s the first occurrence of a specific <see cref="ISchedule"/>
/// from this <see cref="IScheduler"/>.
/// </summary>
/// <param name="schedule">The <see cref="ISchedule"/> to remove from this <see cref="IScheduler"/>.</param>
/// <exception cref="System.ArgumentNullException">Is thrown when the parameter schedule is null.</exception>
/// <exception cref="System.ArgumentException">Is thrown when the <see cref="ISchedule"/> is not found in this <see cref="IScheduler"/> or was of the wrong type.</exception>
void Remove(ISchedule schedule);

Как вы можете видеть почти каждое существительное, на которое можно ссылаться, используя тег <see cref>.
Я нахожу это слишком много. Большинство наших файлов кода настолько взорваны такими комментариями. Делает раздел комментариев почти нечитаемым.

Как вы думаете? Вам нравится такая документация в коде или нет?

Как обычно, я думаю, что нет черного/белого ответа на такой вопрос, почему я сделал это wiki.

EDIT:
Мой вопрос был не в том, что сами теги see-ref полезны по умолчанию. Понятно, что сгенерированные ссылки в файле .chm(или любой другой сгенерированный документ) очень полезны. Мой вопрос заключался в том, что действительно полезно отметить каждое появление каждого "связующего" существительного в комментариях.
Мы используем Sandcastle для генерации документа каждую ночь. К сожалению, он очень редко используется другими разработчиками, но это еще одна проблема.

Ответ 1

Лично я думаю, что у вас немного за борт.

Цель ссылок "видеть" - обеспечить хорошую связь между темами в сгенерированной справочной документации после разбора.

В вашем случае ваши бизнес-специфические библиотеки ссылаются на языковые элементы, то есть:

<see langword="true"/>

Я лично считаю, что гиперссылки на другие связанные объекты в вашей библиотеке - очень полезная функция. Это делает чтение справки более удобным для пользователей.

Гиперссылки на языковые элементы - это то, что, по моему мнению, должно существовать только внутри самой языковой помощи. В случае сторонней библиотеки это просто "путает" сообщение, помещая ссылки повсюду. Это делает хорошие ссылки менее эффективными, так как они скрываются в беспорядке.

Я бы предложил либеральное использование ссылок на связанные классы в вашей библиотеке. Я бы не стал добавлять гиперссылки к базовым классам библиотек, за исключением особых случаев, когда это особенно полезно по какой-либо причине (редко). Связывание с "true" и "IDisposable.Dispose" и т.д. На самом деле не добавляет большого значения.

Доверяйте своему пользователю понять базовую структуру, но расскажите им о своей библиотеке.

Ответ 2

Точка в том, что, когда что-то вроде Sandcastle используется для создания HTML или CHM-документов для библиотеки, эти документы получают гиперссылку навигации между объектами. Таким образом, возникает вопрос, когда вы используете MSDN, находите ли вы полезным щелкнуть по имени класса, чтобы он перешел на помощь для этого класса, или вы нормально его копируете и вставляете в поле поиска?

Да, он раздувает код (хотя комментарии могут быть свернуты), но если вы действительно отправляете документацию другим, это довольно чертово полезно.

Ответ 3

Когда вы работаете с Visual Studio, вы можете использовать плагин CR_Documentor (он бесплатный, вы можете получить здесь) для WYSiWYG-чтение/запись ваших комментариев. Это похоже на сгенерированную форму помощи Sandcastle или NDoc, но визуализируется "на лету". Это действительно полезно, и вам не нужно заботиться о необработанных комментариях xml вообще.

Ответ 4

Как сказал ctacke, это очень полезно для гиперссылок. Однако, если вы не являетесь отправкой документации, все эти теги делают документацию практически невозможной для чтения. В этом случае документация предназначена для разработчика (edit: INTERNAL), и если он или она не может его прочитать, вы теряете время.

Как правило, я отношусь к первой ссылке на тип или элемент и оставляю остальное несвязанным. Он оставляет комментарии довольно чистыми и по-прежнему обеспечивает значимую привязку.

Ответ 5

Существует особая причина для таких комментариев: их можно использовать для создания документации или для добавления дополнительной информации в автозаполнение. Я согласен, что они слишком многословны и трудны для чтения в большинстве ситуаций, но они хороши для добавления в интерфейс, который вы собираетесь выставлять извне.

Я бы рекомендовал использовать редактор, который позволяет включать и отключать комментарии.

Некоторые языки позволяют хранить комментарии как метаданные по переменным и функциям, что является хорошей альтернативой.