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

我明白完全合格的项目总是会让微软的Sandcastle正确地链接事物，但是所有东西都有必要完全合格吗？

---

西德诺特:Microsoft Sandcastle是否能够链接到.NET Framework帮助文件，还是我通过引用来浪费时间 <see cref="T:System.Collections.Generic.ICollection{T}"/>?

Answer 1

两者兼而有之 约瑟夫 和 本 触及有用的点，但我认为我最近的沙堡经验可能会有所帮助:

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

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

3. 您触及了使用显式指定 成员类型前缀 （例如"T：SuperWidget"），但这比大多数人意识到的更重要:如果使用成员类型前缀，则完全限定名称 需要.这实际上是在MSDN上记录的，但在 非常 印刷精美--见 处理XML文件.更糟糕的是，如果你省略了你得到的完全限定的名字 没有警告 在构建时（！);在最终的Sandcastle渲染中根本不会生成链接。如果显式指定成员类型前缀，还有其他问题-请参阅 消除歧义和解决引用 我关于沙堡实用技巧的文章的一节, 驯服沙堡:记录代码的.NET程序员指南.

Answer 2

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

换句话说，如果你是 using System.Collections.Generic, ，那么你就不必有资格了 ICollection{T}.如果你碰巧定义了你自己的 ICollection{T} 接口在同一个文件中，但是，您 威尔 必须符合前者（以及后者，想到它）。

Answer 3

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

至于完全排位赛，在大多数情况下不需要，但取决于您的使用情况，如 本提到过.只要你引用的是在范围内（或者应该是，如果你引用它，你可能会使用它，或者你应该添加using，以便你的代码不使用完全限定的表单），只有类型就足够了。