dart-documentation

编写 Dart 代码文档

目录

• 核心原则
• 文档注释格式
• 特定结构的文档说明
• 工作流：生成和验证文档
• 示例

核心原则

• 仅使用 ///： 使用 /// 为成员和类型编写文档。切勿使用 /** ... */ 块注释编写文档。
• 内部注释使用 //： 使用标准的 // 注释记录不应出现在生成的公开文档中的实现细节。
• 按句子格式编写： 首词首字母大写（区分大小写的标识符除外），并以句号结尾。
• 力求简洁： 清晰、准确、简练。避免重复方法签名或类名中已能推断的信息。
• 使用 Markdown： 使用标准 Markdown 进行格式化。代码块优先使用反引号围栏（```），而非缩进。避免使用 HTML 标签。

文档注释格式

• 以摘要开头： 首句以简短的第三人称单数摘要开头。
• 将摘要单独成段： 将摘要单独放在一行，后接一个空行，以确保 IDE 工具提示和生成的摘要具有最佳可读性。
• 使用方括号引用： 使用 [identifier] 链接到作用域内的类型、方法或变量。
  • 对于特定成员，使用 [ClassName.memberName]。
  • 对于未命名构造函数，使用 [ClassName.new]。
• 用正文描述参数和返回值： 将参数、返回值和异常的说明融入正文，而非使用冗长的标签（例如 @param）。使用方括号标出参数。
• 将文档注释放在元数据之前： 始终将文档注释放在元数据注解（例如 @override）之前。

特定结构的文档说明

方法和函数

• 副作用： 如果主要目的是产生副作用，则摘要以第三人称动词开头（例如，“连接到服务……”）。
• 返回值： 如果主要目的是返回值，则摘要以名词短语开头（例如，“第 [index] 个元素……”）。

变量和属性

• 非布尔值： 以描述属性是什么的名词短语开头（例如，“当前星期……”）。
• 布尔值： 以“是否”开头，后接名词或动名词短语（例如，“模态框当前是否显示……”）。
• Getter/Setter： 如果属性同时具有 getter 和 setter，只为 getter 编写文档。

类和库

• 类： 以描述该类型实例的名词短语开头。
• 库： 在 library 指令前添加 /// 注释。包含一句摘要、术语说明和代码示例。

工作流：生成和验证文档

为 Dart 软件包编写和验证文档时，请遵循以下顺序工作流。

任务进度

• 1. 使用 /// 和 Markdown 编写文档注释。
• 2. 解析依赖项：运行 dart pub get。
• 3. 确保代码没有错误：运行 dart analyze。
• 4. 生成并验证文档：运行 dart doc --validate-links。
• 5. 检查输出，确认没有缺失的引用或格式警告。
• 6. （可选）在本地运行服务，以验证 UI 渲染效果。

反馈循环：验证

生成文档时，必须验证所有 [references] 都能正确解析。

1. 运行验证器： 执行 dart doc --validate-links .
2. 检查错误： 查看控制台输出，查找失效链接或未解析的符号。
3. 修复： 更正 [brackets] 中的拼写错误，确保引用的成员位于作用域内，或调整导入。重复执行，直到命令运行成功且没有警告。

条件逻辑：在本地查看文档

• 如果需要预览生成的 HTML：
  1. 激活本地服务器：dart pub global activate dhttpd
  2. 提供 doc/api 目录：dart pub global run dhttpd --path doc/api
  3. 在浏览器中打开提供的 localhost URL。

示例

高质量的方法文档

/// Deletes the file at [path].
///
/// Throws an [IOError] if the file could not be found. Throws a
/// [PermissionError] if the file is present but could not be deleted.
void delete(String path) {
  // Implementation details...
}

高质量的属性文档

/// The pH level of the water in the pool.
///
/// Ranges from 0-14, representing acidic to basic, with 7 being neutral.
int get phLevel => _phLevel;
set phLevel(int level) => _phLevel = level;

高质量的布尔值文档

/// Whether the modal should confirm the user's intent on navigation.
bool get shouldConfirm => _shouldConfirm;

带代码示例的高质量类文档

/// The lesser of two numbers.
///
/// ```dart
/// min(5, 3) == 3
/// ```
num min(num a, num b) => (a < b) ? a : b;