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

这两个约瑟夫和奔上有用的点联系,我想我最近的沙堡的经验可能会有所帮助:

1. 编译项目时,如果无法解析文档注释中的引用,Visual Studio通常会通过发出警告立即告诉您是否有效引用,无论这是对您自己的类型还是对系统类型的引用(并且VS尊重你的"使用"声明).

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

3. 您谈到了使用显式指定的成员类型前缀(如"T:SuperWidget"),但这是更为显著比大多数人意识到:如果你使用一个成员类型前缀,那么完全合格的名称是必需的.这实际上是在MSDN上记录的,但是在非常精细的打印中 - 请参阅处理XML文件.更糟糕的是,如果省略完全限定名称,则在构建时不会收到警告(!); 只是在最终的Sandcastle渲染中没有生成链接.如果您明确指定成员类型前缀,还有其他问题 - 请参阅我关于实用Sandcastle提示的文章的消除歧义和解析参考部分,Taming Sandcastle:.NET程序员记录代码的指南.