dart-write-documentation

撰写 Dart API 文档

目录

• 1. 范围和结构
• 2. 语气和开头
• 3. 严格禁止的反模式
• 4. 技术位置和解析
• 5. 链接和 Markdown
• 6. 验证
• 示例

当要求为 Dart 代码撰写或更新文档时，必须严格遵循这些基于“Effective Dart: Documentation”指南的格式规则。

1. 范围和结构

• 面向公共 API： 将文档工作重点放在公共声明上。除非另有明确要求，否则不要为私有成员（以下划线 _ 开头的成员）编写文档，因为它们不会显示在生成的 API 参考网站中。
• 始终使用 ///： 所有 API 文档都使用连续的 /// 行注释。切勿使用 /** ... */ 块注释。
• 使用完整句子： 所有注释都应写成完整句子。首词首字母大写（除非它是小写标识符），并以句号结尾。
• 第一段： 文档注释的第一段必须是一个简洁的句子，用于概述对应元素，并以句号结尾。Dartdoc 会在列表视图中原样提取这句话。
• 分隔： 第一条概述句和其余文档之间必须始终用包含 /// 的空行隔开。切勿输出完全空白的行（例如，不含 /// 的 \n），因为这会终止文档注释块。

2. 语气和开头

• 属性使用名词短语： 描述变量、getter 或 setter 时，以名词短语开头。 /// 球体的半径。（不要写“获取半径……”）
• 布尔值使用“是否”： 描述布尔属性时，以“是否”开头。 /// 连接是否处于活动状态。
• 方法使用第三人称动词： 描述方法或函数时，以表示其行为的第三人称动词开头。 /// 初始化数据库。（不要写“初始化”或“此方法会初始化”）
• 避免冗余： 不要复述签名或元素名称。不要写“这个类是……”或“foo 方法会……”。

3. 严格禁止的反模式

• 禁止使用 Javadoc/TSDoc 标签（@param、@return、@throws 等）： 切勿使用 Javadoc 风格的标签（@param、@return、@returns、@throws、@exception、@see、@type）。请将参数名称、返回行为和异常信息自然融入正文。

4. 技术位置和解析

• 注解（@override 等）： 文档注释必须放在元数据注解之前。
• 继承文档： 如果 @override 成员的行为与超类或接口相同，请避免重复编写文档注释。Dartdoc 会自动继承基类文档。
• Getter/Setter 配对： 如果某个属性同时具有 getter 和 setter，只在 getter 上编写文档。两者都编写文档时，工具会发出警告。
• 默认构造函数： 在文档注释中链接到默认的无名构造函数时，必须使用 .new 语法（例如 [ClassName.new]）。

5. 链接和 Markdown

• 使用方括号（[identifier]）标记作用域内的符号： 使用方括号链接到任何作用域内的标识符（参数、类、方法、字段和顶层函数），以便 dartdoc 能够解析它们。参数绝不能使用反引号。
• 方法链接中不使用圆括号： 避免在链接中使用圆括号（例如，使用 [String.contains]，而非 [String.contains()]）。
• 关键字和字面量使用反引号： 关键字、字面量和任意表达式都使用反引号（例如，`null`、`true`、`void`）。绝不要用方括号括起关键字（避免使用 [null] 或 [true]）。
• 作用域外的链接： 如果需要链接到当前库未导入的符号，请在文件顶部的 library; 声明上使用 @docImport 指令，而不要添加常规 import。
• 代码块： 代码示例务必标注代码围栏的语言。Dart 使用 ```dart，shell 命令使用 ```sh。不要省略代码块的语言标注，否则 Dartdoc 会尝试自动检测语言，而且经常判断错误。
• 格式： 在首段之后，使用标准 Markdown（粗体、列表等）充分说明边缘情况、抛出的异常以及调用方无法看到的内部行为。

6. 验证

编写或更新文档注释后：

1. 运行 dart analyze，确保所有方括号引用均能正确解析，且不会触发 comment_references 警告。
2. （可选）运行 dart doc，验证生成的文档能正确呈现。

示例

1. 禁用标签与叙述文字

错误：

/// This method fetches data.
/// @param force true to force reload.
/// @return the data
/// @throws NetworkException if host is unreachable.
Data load(bool force) { ... }

正确：

/// Fetches the remote data.
///
/// If [force] is true, this bypasses the local cache and forces a
/// network request.
///
/// Throws a [NetworkException] if the host is unreachable.
Data load(bool force) { ... }

2. 注解位置陷阱

错误：

@override
/// Renders the widget to the screen.
Widget build(BuildContext context) { ... }

正确：

/// Renders the widget to the screen.
@override
Widget build(BuildContext context) { ... }

3. 开场语与语气

错误：

/// Gets if the connection is active.
bool get isActive => _active;

/// This method initializes the connection.
void init() { ... }

正确：

/// Whether the connection is active.
bool get isActive => _active;

/// Initializes the connection.
void init() { ... }

4. 构造函数链接

错误：

/// Creates a new user. Similar to calling [User()].
User.create() { ... }

正确：

/// Creates a new user. Similar to calling [User.new].
User.create() { ... }

5. 作用域外的链接（@docImport）

错误：

import 'package:http/http.dart'; // Adds unnecessary runtime dependency just for docs

/// To use this, you must pass a [Client].

正确：

/// @docImport 'package:http/http.dart';
library;

/// To use this, you must pass a [Client].