Back to Details

dart-documentation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

dart-documentation

Dart 文档

Goal

目标

Generates, formats, and validates Dart documentation comments and API reference sites according to Effective Dart guidelines. Assumes a standard Dart or Flutter project environment with the Dart SDK installed and accessible.
遵循《Effective Dart》指南，生成、格式化并校验Dart文档注释和API参考站点。适用环境为已安装且可正常访问Dart SDK的标准Dart或Flutter项目环境。

Instructions

使用说明

  1. Analyze the Target Declaration Review the Dart code requiring documentation. Identify the declaration type (e.g., library, class, method, getter/setter, variable) to determine the appropriate phrasing and structure.
  2. Apply Phrasing Decision Logic Determine the opening sentence structure based on the following decision tree:
    • Is it a function or method primarily for side effects?
      • -> Start with a third-person verb (e.g., "Connects to...", "Starts the...").
    • Is it a non-boolean variable, property, or a method conceptually returning a value?
      • -> Start with a noun phrase (e.g., "The current day...", "The [index]th element...").
    • Is it a boolean variable or property?
      • -> Start with "Whether" followed by a noun/gerund phrase (e.g., "Whether the modal is...").
    • Is it a library or type (class, enum, etc.)?
      • -> Start with a noun phrase describing an instance of the type (e.g., "A chunk of non-breaking output...").
  3. Draft the Doc Comment Write the documentation using 
    ///
    syntax. Place the brief, third-person singular summary on its own line. Leave a blank line before starting the next paragraph.
    dart
    /// 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) { ... }
  4. Format Parameters, Returns, and Exceptions Integrate parameter descriptions, return values, and exceptions into prose using square brackets 
    []
    for in-scope identifiers. Do not use verbose tags like 
    @param
    or 
    @returns
    .
    dart
    /// Defines a flag with the given [name] and [abbreviation].
///
/// Returns a new flag.
///
/// Throws a [DuplicateFlagException] if there is already an option named
/// [name] or there is already an option using the [abbreviation].
Flag addFlag(String name, String abbreviation) => ...
  5. Handle Metadata Annotations Always place doc comments before metadata annotations.
    dart
    /// A button that can be flipped on and off.
@Component(selector: 'toggle')
class ToggleComponent {}
  6. Generate and Validate Documentation STOP AND ASK THE USER: "Would you like me to generate and validate the documentation using the 
    dart doc
    CLI?" If the user confirms, execute the following validation loop:
    bash
    # Ensure dependencies are resolved and code is valid
dart pub get
dart analyze

# Run a dry-run to catch documentation warnings/errors
dart doc --dry-run .
  7. Validate-and-Fix Loop If 
    dart doc --dry-run .
    outputs warnings (e.g., unresolved doc references), parse the output, locate the broken 
    [identifier]
    links, and correct them. Once clean, generate the final docs:
    bash
    dart doc .
# Optionally specify output: dart doc --output=api_docs .
  1. 分析目标声明 检查需要添加文档的Dart代码，识别声明类型（例如库、类、方法、getter/setter、变量），以确定合适的措辞和结构。
  2. 应用措辞决策逻辑 根据以下决策树确定首句结构：
    • 是否为主要用于产生副作用的函数或方法？
      • -> 以第三人称动词开头（例如："Connects to..."、"Starts the..."）。
    • 是否为非布尔类型的变量、属性，或是概念上会返回值的方法？
      • -> 以名词短语开头（例如："The current day..."、"The [index]th element..."）。
    • 是否为布尔类型的变量或属性？
      • -> 以"Whether"开头，后面接名词/动名词短语（例如："Whether the modal is..."）。
    • 是否为库或类型（类、枚举等）？
      • -> 以描述该类型实例的名词短语开头（例如："A chunk of non-breaking output..."）。
  3. 起草文档注释 使用
    ///
    语法编写文档。将简短的第三人称单数摘要单独占一行，开启下一段之前保留空行。
    dart
    /// 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) { ... }
  4. 格式化参数、返回值和异常 将参数描述、返回值和异常说明整合到正文当中，对作用域内的标识符使用方括号
    []
    标记。不要使用
    @param
    或
    @returns
    这类冗余标签。
    dart
    /// Defines a flag with the given [name] and [abbreviation].
///
/// Returns a new flag.
///
/// Throws a [DuplicateFlagException] if there is already an option named
/// [name] or there is already an option using the [abbreviation].
Flag addFlag(String name, String abbreviation) => ...
  5. 处理元数据注解 请始终将文档注释放在元数据注解之前。
    dart
    /// A button that can be flipped on and off.
@Component(selector: 'toggle')
class ToggleComponent {}
  6. 生成并校验文档 请停下并询问用户： "你是否希望我使用
    dart doc
    CLI生成并校验文档？" 如果用户确认，执行以下校验流程：
    bash
    # 确保依赖已安装且代码合法
dart pub get
dart analyze

# 执行试运行，捕获文档相关的警告/错误
dart doc --dry-run .
  7. 校验修复循环 如果
    dart doc --dry-run .
    输出警告（例如未解析的文档引用），解析输出内容，定位损坏的
    [identifier]
    链接并修复。没有报错后，生成最终文档：
    bash
    dart doc .
# 可指定输出路径：dart doc --output=api_docs .

Constraints

约束

  • Syntax: DO use 
    ///
    exclusively for doc comments. NEVER use 
    /** ... */
    or block comments 
    /* ... */
    for documentation.
  • Summary Line: DO begin the first sentence with a brief, third-person singular summary. PREFER placing the summary on its own line for better readability in IDE tooltips.
  • References: DO use square brackets 
    []
    to link to types, methods, or variables in scope (e.g., 
    [Duration.inDays]
    , 
    [Point.new]
    ).
  • Code Blocks: PREFER providing concise code examples for complex logic using markdown backtick blocks (
    dart ...
    ).
  • Redundancy: AVOID redundancy with the surrounding context. Do not spell out the method signature or enclosing class if it is obvious.
  • Properties: DON'T write documentation for both the getter and setter of a property. Document only one (usually the getter).
  • Validation: DO verify generated docs using 
    dart doc --validate-links
    (or 
    --dry-run
    ).
  • Formatting: Capitalize the first word of comments and end with a period.
  • Related Skills: 
    dart-effective-style
    .
  • 语法： 必须仅使用
    ///
    作为文档注释，禁止使用
    /** ... */
    或块注释
    /* ... */
    编写文档。
  • 摘要行： 首句必须为简短的第三人称单数摘要，建议将摘要单独占一行，提升IDE悬停提示的可读性。
  • 引用： 必须使用方括号
    []
    链接作用域内的类型、方法或变量（例如
    [Duration.inDays]
    、
    [Point.new]
    ）。
  • 代码块： 对于复杂逻辑，建议使用markdown反引号块（
    dart ...
    ）提供简洁的代码示例。
  • 冗余： 避免和上下文内容重复，如果方法签名或所属类已经很明确，不需要重复说明。
  • 属性： 不要同时为属性的getter和setter编写文档，仅为其中一个编写即可（通常是getter）。
  • 校验： 必须使用
    dart doc --validate-links
    （或
    --dry-run
    ）校验生成的文档。
  • 格式： 注释首字母大写，句末添加句号。
  • 相关技能： 
    dart-effective-style
    。