XML 注释 - 是否应该查看引用是否完全合格？
基本上，什么时候真正需要（如果有的话）使用完全限定的 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 帮助文件，或者我引用
Basically, when is it truly necessary (if at all) to use a fully qualified xml see reference:
<see cref="T:MyNamespace.Sub.MyType"/> //Option 1
<see cref="T:MyType"> //Option 2
Also, what about referencing to the .NET Framework objects?
<see cref="T:System.Collections.Generic.ICollection{T}"/> //Option 1
<see cref="T:ICollection{T}"/> //Option 2
I understand that fully qualifying items will always allow Microsoft's Sandcastle to link things properly, but is it necessary for everything to be fully qualified?
Sidenote: Will Microsoft Sandcastle be able to link to the .NET Framework help files or am I wasting my time by referencing <see cref="T:System.Collections.Generic.ICollection{T}"/>?
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（3）
约瑟夫和Ben 触及有用的观点，但我认为我最近Sandcastle 经验可能会有所帮助：
当您编译项目时，Visual Studio 通常会立即告诉您您的引用是否有效，如果它无法解析文档注释中的引用，无论是否这是对您自己的类型或系统类型的引用（VS 确实尊重您的“使用”声明）。
在使用本地类型屏蔽系统类型的情况下，需要考虑两种情况：您的签名唯一地限定您的类型（由上面的 (1) 涵盖），或者您的签名完全重复系统类型。后一种情况需要通过完全限定名称来显式消除歧义。
您谈到了显式指定成员类型前缀（例如“T:SuperWidget”）的使用，但这比大多数人意识到的更重要：如果您使用成员类型前缀，则完全限定名称是必需的。这实际上在 MSDN 上有记录，但以非常的细则形式记录 - 请参阅 处理 XML 文件。更糟糕的是，如果您省略完全限定名称，则在构建时不会收到任何警告（！）；在最终的 Sandcastle 渲染中根本不会生成任何链接。如果您明确指定成员类型前缀，还会出现其他问题 - 请参阅我关于实用 Sandcastle 技巧的文章中的消除歧义和解决引用部分，驯服沙堡：.NET编写代码的程序员指南。
Both Joseph and Ben touch on useful points but I think my recent Sandcastle experience may be helpful:
When you compile your project Visual Studio will usually tell you immediately whether your reference is valid by issuing a warning if it cannot resolve a reference in your doc-comments, whether this is a reference to your own types or to system types (and VS does honor your "using" statements).
In the scenario of having a local type masking a system type, there are two cases to consider: your signature uniquely qualifies your type (covered by (1) above), or your signature exactly duplicates a system type. The latter case requires explicit disambiguation by fully qualifying the name.
You touched upon the use of explicitly specifying the member type prefix (e.g. "T:SuperWidget"), but this is more significant than most people realize: if you use a member type prefix then fully qualified names are required. This is actually documented on MSDN but in the very fine print--see Processing the XML File. And to make matters worse, if you omit the fully qualified name you get no warning at build time(!); simply no link is generated in the final Sandcastle rendering. There are other issues if you explicitly specify a member type prefix--see the Disambiguating and Resolving References section of my article on practical Sandcastle tips, Taming Sandcastle: A .NET Programmer's Guide to Documenting Your Code.
我不能代表 Sandcastle 发言，但根据我使用其他工具（例如 ReSharper）的经验，如果 a）它不在范围内或 b）它被另一种类型遮盖，则似乎需要对类型进行限定 -本地定义的。
换句话说，如果您
使用 System.Collections.Generic，则无需限定ICollection{T}。但是，如果您碰巧在同一个文件中定义了自己的ICollection{T}接口，那么您将必须限定前者（以及后者，想想看的）。I can't speak for Sandcastle, but based on my experience with other tools e.g. ReSharper, it seems that a type needs to be qualified if a) it isn't in scope or b) it is shadowed by another type that is more-locally defined.
In other words, if you are
using System.Collections.Generic, then you won't have to qualifyICollection{T}. If you happen to define your ownICollection{T}interface in the same file, however, you will have to qualify the former (as well as the latter, come to think of it).在我看来，您并没有在
至于完全限定，在大多数情况下不需要，但取决于您的使用，如 本提到过。只要您引用的内容在范围内（并且应该是，因为如果您引用它，您可能会使用它，或者您应该添加 using 以便您的代码不使用完全限定的形式），只要类型就足够了。
You are not wasting your time in
<see cref />-ing the Framework, in my opinion. The Visual Studio help provider should be able to intercept and interpret at runtime when the call is made for that help topic. I haven't used it recently, but it had worked quite nicely in the past.As to fully qualifying, it is not needed in most scenarios, but depends on your usings, as Ben has mentioned. As long as what you are referencing is in scope (and either should be, as you are likely to be using it if you are referencing it, or you should add the using so that your code isn't using the fully qualified form), just the type should suffice.