对分部类/方法的 XML 注释

本文关键字：XML 注释 方法 | 更新日期: 2023-09-27 17:56:11

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

  • Visual Studio 用于创建 XML 文档的内置方法
  • Microsoft沙堡

我不希望我的 XML 文档出来时髦是全部

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

对分部类/方法的 XML 注释

最佳做法是只对其中一个部分定义提供 XML 注释。 没有必要将 1 个班级的公众意见分成 2 个地方。（当然，在每个部分定义中都有常规注释仍然有意义。

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

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

相关文章：