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>标签进行引用。

我认为这太多了。我们的大多数代码文件都被这样的注释搞得一团糟。让注释部分几乎无法阅读。

你怎么想？你喜欢在代码中使用这种文档吗？

像往常一样，我认为这种问题没有黑白之分，所以我把它设为维基。

编辑：
我的问题不是默认情况下是否有用的see-ref-tags本身。 很明显，在.chm文件（或任何其他类型的生成文档）中生成的链接非常有用。 我的问题是是否真的有必要在注释中标记每个“可链接”的名词的每个出现。

我们使用Sandcastle每晚生成文档。 不幸的是，其他开发人员极少使用它，但这是另一个问题。

- TomTom

Answer 1

个人认为你所拥有的内容有些过头了。

"see" 引用的目的是在解析后生成的帮助文档中提供良好的主题链接。

在你的情况下，你的业务专用库正在引用语言项，即：

<see langword="true"/>

我个人认为在你的库中添加到其他相关对象的超链接是一个非常有用的功能，这可以使用户更轻松地使用帮助文档。

关于语言元素的超链接，我认为只应该存在于语言自身的帮助文档中。对于第三方库来说，这会使信息变得混乱，因为到处都是链接。这会使得好的链接隐藏在混乱之中，效果变差。

我建议在您的库中大量使用与相关类的链接。除了某些特殊情况（很少发生），我会避免添加到基本库类的超链接。链接到 "true" 和 "IDisposable.Dispose" 等不会真正增加很多价值。

相信你的用户能够理解基本框架，但要教他们如何使用您的库。

- Reed Copsey

---

听起来很有趣。说消费者应该至少知道内置语言标记是有道理的。好观点。 - TomTom

是的 - 当我看到文档到处链接到BCL时，它给我的感觉就像是“说教”。这样做只是假设你的用户不理解他们在做什么。 - Reed Copsey

是的，这就是为什么更倾向于使用<c>null</c>来区分它作为编程语言语法中的关键字，而不是使用“see”引用。 - Ray

那最后一句话太棒了。 - gregsdennis

Answer 2

所有这些的目的是，当类似Sandcastle这样的工具用于为库生成HTML或CHM文档时，这些文档之间会有超链接导航。那么问题来了，当你使用MSDN时，你觉得能够点击类名并导航到该类的帮助信息很有用，还是你只想将其复制并粘贴到搜索框中？是的，它会使代码变得臃肿（尽管注释可以折叠），但如果你实际上要向他人提供文档，它非常有用。

- ctacke

---

当使用ReSharper的“快速文档”功能（在我的键映射中为Ctrl-Q）时，它也非常有用。 - adrianbanks

Answer 3

当你使用Visual Studio时，你可以使用CR_Documentor插件（免费的，你可以在这里获取）来所见即所得地阅读/编写你的注释。它看起来像是由Sandcastle或NDoc生成的帮助文档，但是它是实时渲染的。这非常有用，你不需要关心原始的xml注释。

- Thomas Weller

Answer 4

如ctacke所说，它非常适用于超链接。然而，如果您实际上没有发布文档，所有这些标记使得文档几乎不可能阅读。在这种情况下，文档是给（编辑：内部）开发者的，如果他或她无法阅读它，则浪费了您的时间。

通常，我倾向于链接到类型或成员的第一个引用，并保留其余部分未链接。这样可以使注释非常清晰，并仍然提供有意义的链接。

- Mike Hofer

Answer 5

这些注释有一个特定的原因：它们可以用于生成文档或向自动完成添加额外信息。我同意它们在大多数情况下过于冗长且难以阅读，但是将它们添加到要对外部公开的接口中是很好的。

我建议使用允许您打开和关闭注释的编辑器。

一些语言允许您将注释存储为变量和函数的元数据，这是一个不错的替代方案。

- GlennS