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

Question

В нашей компании мы пишем чрезмерные комментарии 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>.
Я нахожу это слишком много. Большинство наших файлов кода так взорваны такими комментариями. Делает раздел комментариев почти нечитаемым.

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

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

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

Answer 1

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

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

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

<see langword="true"/>

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

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

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

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

Answer 2

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

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

Answer 3

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

Answer 4

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

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

Answer 5

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

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

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