c# - 对部分类/方法的 XML 注释

Question

用于生成 API 文档的工具是否有一种标准方法来处理对部分类的 XML 样式注释？基本上，应该如何评论部分类/方法，以便生成的帮助文档不被破坏？这个问题可能因使用的工具而异，在这种情况下，我想最重要的两个工具是:

• Visual Studio 的内置方法来创建 XML 文档
• 微软的 SandcaSTLe

我不希望我的 XML 文档看起来很时髦

/// <summary>Some Foo class</summary>
public partial class Foo { ... }

/// <summary>Some Foo class that implements some interface.</summary>
public partial class Foo : ISomeInterface { ... }

Answer 1

最佳做法是为 仅 1 个部分定义 提供 XML 注释。应该没有必要将 1 个类的公共(public)评论分成 2 个地方。 (当然，每个部分定义中的常规注释仍然有意义。)

Visual Studio 的工作方式是一个部分定义中的注释将覆盖另一个。您可以通过使用不同的 XML 注释创建同一类的 2 个部分定义来确认这一点，然后创建一个这种类型的变量。智能感知将仅显示 1 个 XML 注释。

这也将是任何使用 Visual Studio 生成的 XML 注释文件的文档工具的行为，其中包括 SandcaSTLe。