编写 Dart API 文档注释时如何遵循…

在为 Dart 代码编写或更新 /// 文档注释时，按 Effective Dart 规范组织内容、语气、链接与验证。

适用场景

解决思路

1. 只为公共声明编写文档，除非明确要求，否则不要为以下划线 `_` 开头的私有成员编写文档，因为它们不会出现在生成的 API 参考站点中。
2. 所有 API 文档一律使用连续的 `///` 行注释，绝不使用 `/** ... */` 块注释。
3. 把所有注释写成规范的句子：首词大写（除非是小写标识符），并以句号结尾。
4. 文档注释的第一段必须是一句简洁的总结句，并以句号结尾；dartdoc 会原样提取它用于列表视图。
5. 始终用包含 `///` 的空行把第一句总结与其余文档分隔开；绝不输出完全空的新行（例如没有 `///` 的 `\n`），否则会终止文档注释块。
6. 变量、getter 或 setter 的描述以名词短语开头，例如 `/// The radius of the sphere.`，而不是 “Gets the radius...”。
7. 布尔属性的文档以 “Whether” 开头，例如 `/// Whether the connection is active.`。
8. 方法或函数的描述以第三人称动词开头说明其作用，例如 `/// Initializes the database.`，而不是 “Initialize” 或 “This method initializes”。
9. 避免冗余：不要复述签名或元素名称，不要写 “This class is a...” 或 “The foo method does...”。
10. 绝不使用 Javadoc/TSDoc 风格标签（`@param`、`@return`、`@returns`、`@throws`、`@exception`、`@see`、`@type` 等），而要把参数名、返回行为和异常融入正文叙述。
11. 文档注释必须放在元数据注解（如 `@override`）之前。
12. 对于 `@override` 成员，如果行为与父类或接口没有差异，就避免重复文档注释；dartdoc 会自动继承基类文档。
13. 如果属性同时有 getter 和 setter，只在 getter 上放置文档；若两者都写文档，工具会发出警告。
14. 要在文档注释中链接默认的匿名构造函数，必须使用 `.new` 语法（例如 `[ClassName.new]`）。
15. 使用方括号 `[identifier]` 链接任何作用域内的标识符（参数、类、方法、字段和顶层函数），以便 dartdoc 解析；绝不要用反引号表示参数。
16. 方法链接中不要带括号（例如用 `[String.contains]`，而不是 `[String.contains()]`）。
17. 关键字、字面量和任意表达式使用反引号（例如 `` `null` ``、`` `true` ``、`` `void` ``）；绝不把关键字放在方括号中（避免 `[null]` 或 `[true]`）。
18. 如果需要链接当前库未导入的符号，在文件顶部（`library;` 声明上）使用 `@docImport` 指令，而不是添加常规 `import`。
19. 代码示例始终标注语言围栏：Dart 用 ```dart，shell 命令用 ```sh；不要留下未标注的代码块，因为 Dartdoc 会尝试自动检测语言且经常猜错。
20. 在第一段之后使用标准 Markdown（加粗、列表等）充分说明边界情况、抛出的异常以及调用者看不到的内部行为。
21. 编写或更新文档注释后，运行 `dart analyze` 确保所有方括号引用都能正确解析且不触发 `comment_references` 警告。
22. （可选）运行 `dart doc` 验证生成的文档渲染是否干净。

适用边界 · 注意事项

• 不要为私有成员（以下划线 `_` 开头）编写文档，除非明确要求。
• 不要在 `@override` 成员行为与父类或接口无差异时重复文档注释。
• 不要为同时有 getter 和 setter 的属性在两者上都写文档。