文档注释规范重点

文档注释可以是多行注释，也可以是单行注释，文档注释以 /// 或者 /** 开始。在连续行上使用 /// 与多行文档注释具有相同的效果。推荐使用 /// 是因为其更加简洁。 /** 和 */ 在多行注释中间添加了开头和结尾的两行多余内容。 /// 在一些情况下也更加易于阅读，例如，当文档注释中包含有使用 * 标记的列表内容的时候。
在文档注释中，除非用中括号括起来，否则 Dart 编译器会忽略所有文本。使用中括号可以引用类、方法、字段、顶级变量、函数和参数。括号中的符号会在已记录的程序元素的词法域中进行解析。

如果给变量，方法，或类型等名称加上方括号，则 dartdoc 会查找名称并链接到相关的 API 文档。括号是可选的，但是当你在引用一个方法或者构造函数时，可以让注释更清晰。

/// Throws a [StateError] if ...
/// similar to [anotherMethod()], but ...

要链接到特定类的成员，请使用以点号分割的类名和成员名：

/// Similar to [Duration.inDays], but handles fractional days.

点语法也可用于引用命名构造函数。对于未命名的构造函数，在类名后面加上括号：

/// To create a point, call [Point()] or use [Point.polar()] to ...

下面是一个引用其他类和成员的文档注释：
/// A domesticated South American camelid (Lama glama).
///
/// Andean cultures have used llamas as meat and pack
/// animals since pre-Hispanic times.
class Llama {
String name;

/// Feeds your llama [Food].
///
/// The typical llama eats one bale of hay per week.
void feed(Food food) {
// …
}

/// Exercises your llama with an [activity] for
/// [timeLimit] minutes.
void exercise(Activity activity, int timeLimit) {
// …
}
}
在生成的文档中，[Food] 会成为一个链接，指向 Food 类的 API 文档。

要 使用散文的方式来描述参数、返回值以及异常信息。

其他语言使用各种标签和额外的注释来描述参数和返回值。

错误示范❌
/// Defines a flag with the given name and abbreviation.
///
/// @param name The name of the flag.
/// @param abbr The abbreviation for the flag.
/// @returns The new flag.
/// @throws ArgumentError If there is already an option with
///     the given name or abbreviation.
Flag addFlag(String name, String abbr) => ...

而 Dart 把参数、返回值等描述放到文档注释中， 并使用方括号来引用以及高亮这些参数和返回值。

正确
/// Defines a flag.
///
/// Throws an [ArgumentError] if there is already an option named [name] or
/// there is already an option using abbreviation [abbr]. Returns the new flag.
Flag addFlag(String name, String abbr) => ...

要 把注释文档放到注解之前。

正确
/// A button that can be flipped on and off.
@Component(selector: 'toggle')
class ToggleComponent {}

错误示范❌
@Component(selector: 'toggle')
/// A button that can be flipped on and off.
class ToggleComponent {}