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}"/>时在浪费时间？

- myermian

---

当你拥有一个与你想要使用cref的类型同名的属性时，这将有所帮助——如果没有命名空间，它将无法被解析，编译器会认为你在讨论该属性。 - CAD bloke

Answer 1

无论是Joseph还是Ben都提到了有用的观点，但我认为我最近的沙堡体验可能会有所帮助：

1. 当你编译项目时，Visual Studio通常会立即告诉你是否引用有效，如果无法解析doc-comments中的引用，无论是对自己的类型还是系统类型的引用（VS确实尊重你的“using”语句），都会发出警告。

2. 在本地类型掩盖系统类型的情况下，有两种情况需要考虑：你的签名唯一标识了你的类型（由上面的(1)涵盖），或者你的签名完全复制了一个系统类型。后一种情况需要通过完全限定名称进行明确消歧。

3. 你提到了显式指定成员类型前缀的用法（例如“T:SuperWidget”），但这比大多数人意识到的要重要得多：如果你使用成员类型前缀，则需要完全限定名称。这实际上在MSDN上有记录，但在非常细微的地方--请参见处理XML文件。更糟糕的是，如果省略完全限定名称，则在构建时不会收到任何警告(!); 在最终的Sandcastle渲染中，只是没有生成链接。如果你显式指定成员类型前缀，还有其他问题--请参见我关于实用Sandcastle技巧的文章中的消歧和解析引用部分，驯服Sandcastle：.NET程序员指南来记录你的代码。

- Michael Sorens

---

很好的回答和文章，谢谢。 - Joseph Yaduvanshi

Answer 2

我不能代表 Sandcastle，但根据我的经验，使用其他工具如 ReSharper，似乎需要对类型进行限定，如果 a) 它不在作用域内，或者 b) 它被另一个更局部定义的类型遮蔽。

换句话说，如果你使用 System.Collections.Generic，那么你不必限定 ICollection{T}。然而，如果你在同一文件中定义自己的 ICollection{T} 接口，你就必须限定前者（以及后者，考虑一下）。

- Ben

---

这正是我想的，尤其是在查看实际的Microsoft代码之后，他们甚至没有标记实际类型（属性或类型或字段等）。但是，我想确认一下。 - myermian

Answer 3

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

至于完全限定名，在大多数情况下是不需要的，但取决于你的usings，就像Ben已经提到的那样。只要你引用的内容在范围内（如果你正在引用它，很可能会这样），或者你应该添加using以使你的代码不使用完全限定形式，只需要类型即可。

- Joseph Ferris