csharp-docs

C# 文档最佳实践

• 公共成员应使用 XML 注释进行文档化。
• 鼓励也对内部成员进行文档化，尤其是当它们较为复杂或含义不够直观时。

所有 API 的指南

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

方法

• 使用 <param> 描述方法参数。
  • 描述应为一个名词短语，不指明数据类型。
  • 以不定冠词开头。
  • 如果参数是标志枚举，描述应以“A bitwise combination of the enumeration values that specifies...”开头。
  • 如果参数是非标志枚举，描述应以“One of the enumeration values that specifies...”开头。
  • 如果参数是布尔值，措辞应采用“<see langword="true" /> to ...; otherwise, <see langword="false" />.”的形式。
  • 如果参数是“out”参数，措辞应采用“When this method returns, contains .... This parameter is treated as uninitialized.”的形式。
• 使用 <paramref> 在文档中引用参数名称。
• 使用 <typeparam> 描述泛型类型或方法中的类型参数。
• 使用 <typeparamref> 在文档中引用类型参数。
• 使用 <returns> 描述方法返回的内容。
  • 描述应为一个名词短语，不指明数据类型。
  • 以不定冠词开头。
  • 如果返回类型是布尔值，措辞应采用“<see langword="true" /> if ...; otherwise, <see langword="false" />.”的形式。

构造函数

• 摘要措辞应为“Initializes a new instance of the class [or struct].”。

属性

• <summary> 应以以下内容开头：
  • 对于读写属性，使用“Gets or sets...”。
  • 对于只读属性，使用“Gets...”。
  • 对于返回布尔值的属性，使用“Gets [or sets] a value that indicates whether...”。
• 使用 <value> 描述属性的值。
  • 描述应为一个名词短语，不指明数据类型。
  • 如果属性有默认值，请将其添加在单独的句子中，例如“The default is <see langword="false" />”。
  • 如果值类型是布尔值，措辞应采用“<see langword="true" /> if ...; otherwise, <see langword="false" />. The default is ....”的形式。

异常

• 使用 <exception cref> 记录构造函数、属性、索引器、方法、运算符和事件引发的异常。
• 记录成员直接引发的所有异常。
• 对于嵌套成员引发的异常，只记录用户最有可能遇到的异常。
• 异常的说明描述引发该异常的条件。
  • 省略句首的“Thrown if ...”或“If ...”。直接陈述条件即可，例如“An error occurred when accessing a Message Queuing API.”