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

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

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

РЕДАКТИРОВАТЬ:
Мой вопрос был не в том, полезны ли сами теги see-ref по умолчанию. Понятно, что сгенерированные ссылки в файле .chm (или любом другом сгенерированном документе) очень полезны. Мой вопрос заключался в том, действительно ли полезно помечать в комментариях каждое вхождение каждого «ссылаемого» существительного.
Мы используем Sandcastle для создания документа каждую ночь. К сожалению, он очень редко используется другими разработчиками, но это другой вопрос.


xml c# comments
person Community    schedule 06.10.2009    source источник

Ответы (5)


arrow_upward
13
arrow_downward

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

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

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

<see langword="true"/>

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

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

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

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

person Community    schedule 06.10.2009
comment
Звучит интересно. Имеет смысл сказать, что потребитель моей библиотеки должен, по крайней мере, теперь использовать токены встроенного языка. Хорошая точка зрения. - person TomTom; 06.10.2009
comment
Да, когда я повсюду вижу документы, ссылающиеся на BCL, это кажется мне проповедью. Это просто предполагает, что ваш пользователь не понимает, что он делает. - person Reed Copsey; 06.10.2009
comment
Да, именно поэтому предпочтительнее использовать <c>null</c>, чтобы различать его как ключевое слово, принадлежащее синтаксису языка кодирования, а не использовать ссылки "see". - person Ray; 29.01.2010
comment
Последняя фраза потрясающая. - person gregsdennis; 01.12.2016

arrow_upward
6
arrow_downward

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

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

person Community    schedule 06.10.2009
comment
Это также очень полезно при использовании функции быстрого документирования ReSharper (Ctrl-Q в моих сопоставлениях клавиш). - person adrianbanks; 06.10.2009

arrow_upward
4
arrow_downward

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

person Community    schedule 06.10.2009

arrow_upward
3
arrow_downward

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

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

person Community    schedule 06.10.2009

arrow_upward
1
arrow_downward

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

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

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

person Community    schedule 06.10.2009