24

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

4

3 回答 3

16

Joseph和Ben都谈到了有用的观点，但我认为我最近的 Sandcastle 经历可能会有所帮助：

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

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

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

于 2011-05-15T20:22:18.290 回答
3

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

至于完全排位赛，在大多数情况下不需要，但取决于您的使用，正如Ben 提到的那样。只要您引用的内容在范围内（或者应该是，因为如果您引用它，您可能会使用它，或者您应该添加 using 以便您的代码不使用完全限定的形式），只要类型就足够了。

于 2011-05-13T17:45:10.353 回答
3

我不能代表 Sandcastle，但根据我使用其他工具（例如 ReSharper）的经验，似乎需要限定一个类型，如果 a）它不在范围内或 b）它被另一种更多的类型所掩盖 -本地定义。

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

于 2011-05-13T17:24:01.073 回答