XML注释 - 应该看到引用完全合格吗？

Question

基本上，何时真正需要（如果有的话）使用完全限定的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}"/>来浪费时间？

Answer 1

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

1. 编译项目时，如果无法解析文档注释中的引用，Visual Studio通常会通过发出警告立即告诉您是否有效引用，无论这是对您自己的类型的引用还是系统类型（VS确实尊重您的“使用”语句）。

2. 在具有屏蔽系统类型的本地类型的情况下，有两种情况需要考虑：您的签名唯一限定您的类型（由上面的（1）覆盖），或者您的签名完全复制系统类型。后一种情况需要通过完全限定名称来明确消除歧义。

3. 您谈到使用明确指定成员类型前缀（例如“T：SuperWidget”），但这比大多数人意识到的更重要：如果您使用成员类型前缀然后是完全限定名称​​是必需的。这实际上是在MSDN上记录的，但在非常精细打印中 - 请参阅Processing the XML File。更糟糕的是，如果省略完全限定名称，则在构建时会得到 no warning （！）;只是在最终的Sandcastle渲染中没有生成链接。如果您明确指定成员类型前缀，还有其他问题 - 请参阅我的文章中有关实用Sandcastle提示的消除歧义和解析参考部分，Taming Sandcastle: A .NET Programmer's Guide to Documenting Your Code。

Answer 2

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

换句话说，如果您是using System.Collections.Generic，那么您就不必拥有ICollection{T}资格。但是，如果您碰巧在同一个文件中定义了自己的ICollection{T}接口，那么将必须对前者进行限定（以及后者，请考虑它）。

Answer 3

在我看来，你并没有在<see cref />框架中浪费你的时间。在为该帮助主题进行调用时，Visual Studio帮助提供程序应该能够在运行时进行拦截和解释。我最近没有使用它，但它过去工作得非常好。

至于完全合格，在大多数情况下都不需要，但取决于您的使用情况，如Ben has mentioned。只要您引用的内容在范围内（并且应该是，或者您可能正在使用它，如果您引用它，或者您应该添加使用以便您的代码不使用完全限定的表单），只要这种类型就足够了。