C#XML注释:XML注释中有多少<see ... />引用有用？

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"引用的目的是在解析后在生成的帮助文档中提供主题之间的良好链接.

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

<see langword="true"/>

我个人认为,库中其他相关对象的超链接是一个非常有用的功能.它使阅读帮助对您的用户更有用.

语言元素的超链接是我认为应该只存在于语言帮助本身内部的东西.在第三方图书馆的情况下,这只是通过在任何地方放置链接来"混淆"消息.这使得良好的链接效率降低,因为它们隐藏在混乱中.

我建议自由使用链接到库中的相关类.我会避免添加到基本库类的超链接,除非在特定情况下由于某种原因特别有用(罕见).链接到"true"和"IDisposable.Dispose"等,并没有真正增加很多价值.

相信您的用户了解基础框架,但教他们有关您的库.

Answer 2

所有这些的要点是,当使用像Sandcastle这样的东西为库生成HTML或CHM文档时,那些文档会在对象之间获得超链接导航.那么问题是,当你使用MSDN时,你发现能够点击类名是否有用,导航到该类的帮助,或者你可以复制它并将其粘贴到搜索字段中吗？

是的,它会使代码膨胀(尽管注释可能会崩溃),但是如果您实际上将文档发送给其他人,那么它非常有用.