C# 文档编写最佳实践

• 公共成员应使用 XML 注释进行文档记录。
• 也建议对内部成员进行文档记录，尤其是在它们复杂或不言自明的情况下。

所有 API 的通用指南

• 使用 <summary> 提供类型或成员功能的简要描述（一句话）。摘要应以现在时、第三人称动词开头。
• 使用 <remarks> 提供补充信息，可以包括实现细节、使用说明或任何其他相关上下文。
• 对特定于语言的关键字（如 null、true、false、int、bool 等）使用 <see langword>。
• 对内联代码片段使用 <c>。
• 对成员的使用示例使用 <example>。
  • 对代码块使用 <code>。<code> 标签应放置在 <example> 标签内。使用 language 属性指定代码示例的语言，例如，<code language=“csharp”>。
• 使用 <see cref> 在行内（句子中）引用其他类型或成员。
• 使用 <seealso> 在在线文档的“另请参阅”部分中，独立（不在句子中）引用其他类型或成员。
• 使用 <inheritdoc/> 从基类或接口继承文档。
  • 除非行为发生重大变化，在这种情况下，您应该记录差异。

方法

• 使用 <param> 描述方法参数。
  • 描述应为名词短语，不指定数据类型。
  • 以引导性冠词开头。
  • 如果参数是标志枚举，描述以“指定……的枚举值的按位组合。”开头。
  • 如果参数是非标志枚举，描述以“指定……的枚举值之一。”开头。
  • 如果参数是布尔值，措辞应为“<see langword=“true” /> 用于……；否则为 <see langword=“false” />。”的形式。
  • 如果参数是“out”参数，措辞应为“当此方法返回时，包含……。此参数被视为未初始化。”的形式。
• 使用 <paramref> 在文档中引用参数名称。
• 在泛型类型或方法中，使用 <typeparam> 描述类型参数。
• 使用 <typeparamref> 在文档中引用类型参数。
• 使用 <returns> 描述方法的返回值。
  • 描述应为名词短语，不指定数据类型。
  • 以引导性冠词开头。
  • 如果返回类型是布尔值，措辞应为“<see langword=“true” /> 如果……；否则为 <see langword=“false” />。”的形式。

构造函数

• 摘要的措辞应为“初始化类 [或结构] 的新实例。”

属性

• <summary> 应以以下内容开头：
  • “获取或设置……”用于读写属性。
  • “获取……”用于只读属性。
  • “获取 [或设置] 一个指示是否……的值”用于返回布尔值的属性。
• 使用 <value> 描述属性的值。
  • 描述应为名词短语，不指定数据类型。
  • 如果属性有默认值，请在单独的句子中添加，例如，“默认值为 <see langword=“false” />”。
  • 如果值类型是布尔值，措辞应为“<see langword=“true” /> 如果……；否则为 <see langword=“false” />。默认值为……”的形式。

异常

• 使用 <exception cref> 记录构造函数、属性、索引器、方法、运算符和事件抛出的异常。
• 记录成员直接抛出的所有异常。
• 对于嵌套成员抛出的异常，只记录用户最可能遇到的异常。
• 异常的描述说明了抛出异常的条件。
  • 省略句子开头的“如果……则抛出”或“当……”。直接陈述条件，例如，“访问消息队列 API 时发生错误。”