C# XML Comments : How many 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> 来引用标签。
我觉得这太多了。我们的大部分代码文件都被这样的注释弄得乱七八糟。使评论部分几乎不可读。

你怎么看？你喜欢代码中的这种文档吗？

像往常一样，我认为对于此类问题没有非黑即白的答案，这就是我将其制作为 wiki 的原因。

编辑:
我的问题不是默认情况下 see-ref-tags 本身是否有用。很明显，.chm 文件(或任何其他类型的生成文档)中生成的链接非常有用。我的问题是标记评论中每个“可链接”名词的每次出现是否真的有用。
我们每晚都使用 SandcaSTLe 生成文档。不幸的是，它很少被其他开发人员使用，但这是另一个问题。

Answer 1

就我个人而言，我认为您的做法有些过分。

“查看”引用的目的是在解析后生成的帮助文档中的主题之间提供良好的链接。

在您的情况下，您的业务特定库正在引用语言项目，即:

<see langword="true"/>

我个人觉得您图书馆中其他相关对象的超链接是一个非常有用的功能。它使阅读帮助对您的用户更有用。

我觉得语言元素的超链接应该只存在于语言帮助本身。在第三方库的情况下，这只是通过在各处放置链接来“混淆”消息。这会使好的链接变得不那么有效，因为它们隐藏在困惑中。

我建议自由使用链接到您的库中的相关类。我会避免向基库类添加超链接，除非在特定情况下它出于某种原因特别有用(很少见)。链接到“true”和“IDisposable.Dispose”等并没有真正增加很多值(value)。

相信您的用户了解基本框架，但向他们介绍您的库。