XML 注释 - 是否应该看到引用是完全限定的？答案

【问题标题】：XML Comments - Should see references be fully qualified?XML 注释 - 是否应该看到引用是完全限定的？
【发布时间】：2011-05-13 15:56:31
【问题描述】：

基本上，什么时候真正需要（如果有的话）使用完全限定的 xml，请参阅参考：

<see cref="T:MyNamespace.Sub.MyType"/> //Option 1
<see cref="T:MyType"> //Option 2

另外，如何引用 .NET Framework 对象？

<see cref="T:System.Collections.Generic.ICollection{T}"/> //Option 1
<see cref="T:ICollection{T}"/> //Option 2

我了解完全合格的项目将始终允许 Microsoft 的 Sandcastle 正确链接事物，但是否有必要使所有内容都完全合格？

旁注：Microsoft Sandcastle 是否能够链接到 .NET Framework 帮助文件，还是我引用 <see cref="T:System.Collections.Generic.ICollection{T}"/> 是在浪费时间？

【问题讨论】：

【解决方案1】：

Joseph 和 Ben 都提到了有用的点，但我认为我最近的 Sandcastle 体验可能会有所帮助：

当您编译项目时，Visual Studio 通常会立即告诉您您的引用是否有效，如果它无法解析您的 doc-cmets 中的引用，无论这是对您自己的类型的引用还是对系统类型（并且 VS 确实尊重您的“使用”语句）。
在使用本地类型屏蔽系统类型的情况下，有两种情况需要考虑：您的签名唯一地限定您的类型（由上面的 (1) 涵盖），或者您的签名与系统类型完全重复。后一种情况需要通过完全限定名称来明确消除歧义。
您谈到了使用显式指定成员类型前缀（例如“T:SuperWidget”），但这比大多数人意识到的更重要：如果您使用成员类型前缀然后是完全限定的名称是必需的。这实际上记录在 MSDN 上，但在 very 精美印刷品中 - 请参阅 Processing the XML File。更糟糕的是，如果你省略了完全限定的名称，你会在构建时得到no warning(!);在最终的 Sandcastle 渲染中根本没有生成链接。如果您明确指定成员类型前缀，还有其他问题 - 请参阅我关于实用 Sandcastle 技巧的文章中的消除歧义和解决引用部分，Taming Sandcastle: A .NET Programmer's Guide to Documenting Your Code。

【讨论】：

【解决方案2】：

我不能代表 Sandcastle，但根据我使用其他工具的经验，例如ReSharper，似乎需要限定一个类型，如果 a) 它不在范围内，或者 b) 它被另一种更本地定义的类型所遮蔽。

换句话说，如果您是using System.Collections.Generic，那么您不必符合ICollection{T} 的条件。但是，如果您碰巧在同一个文件中定义了自己的 ICollection{T} 接口，您将必须限定前者（以及后者，想想看）。

【讨论】：

【解决方案3】：

在我看来，您不会在 <see cref />-ing 框架上浪费时间。当针对该帮助主题进行调用时，Visual Studio 帮助提供程序应该能够在运行时拦截和解释。我最近没有使用它，但它在过去工作得很好。

至于完全限定，在大多数情况下不需要，但取决于您的使用，如Ben has mentioned。只要您引用的内容在范围内（或者应该是，因为如果您引用它，您可能会使用它，或者您应该添加 using 以便您的代码不使用完全限定的形式），只要类型就足够了。

【讨论】：