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

最佳做法是为部分定义中的一个提供XML注释。不需要将1个类的 public 注释拆分为2个位置。（当然，在每个部分定义中，常规注释仍然有意义。）

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

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

XML评论部分类/方法

1 个答案: