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> 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.”。