/// Returns `true` if every element satisfies the [predicate].
bool all(bool predicate(T element)) => ...
/// Starts the stopwatch if not already running.
void start() {
推荐 使用名词短语来为非布尔值变量或属性注释。
注释文档应该表述这个属性是什么。虽然 getter 函数会做些计算，但是也要求这样，调用者关心的是其结果而不是如何计算的。
/// The current day of the week, where `0` is Sunday.
int weekday;
/// The number of checked buttons on the page.
int get checkedCount => ...
PREFER starting a boolean variable or property comment with “Whether” followed by a noun or gerund phrase.
The doc comment should clarify the states this variable represents.
This is true even for getters which may do calculation or other work.
What the caller cares about is the result of that work, not the work itself.
/// Whether the modal is currently displayed to the user.
bool isVisible;
/// Whether the modal should confirm the user's intent on navigation.
bool get shouldConfirm => ...
/// Whether resizing the current browser window will also resize the modal.
bool get canResize => ...
This guideline intentionally doesn’t include using “Whether or not”. In many
cases, usage of “or not” with “whether” is superfluous and can be omitted,
especially when used in this context.
DON’T write documentation for both the getter and setter of a property.
如果一个属性同时包含 getter 和 setter，请只为其中一个添加文档。
dart doc 命令会将 getter 和 setter 作为同一个属性进行处理，而如果它们都包含文档注释，dart docs 命令会将 setter 的文档忽略。
/// The pH level of the water in the pool.
/// Ranges from 0-14, representing acidic to basic, with 7 being neutral.
int get phLevel => ...
set phLevel(int level) => ...
/// The depth of the water in the pool, in meters.
int get waterDepth => ...
/// Updates the water depth to a total of [meters] in height.
set waterDepth(int meters) => ...
推荐 使用名词短语来开始库和类型注释。
在程序中，类的注释通常是最重要的文档。类的注释描述了类型的不变性、介绍其使用的术语、提供类成员使用的上下文信息。为类提供一些注释可以让其他类成员的注释更易于理解和编写。
/// A chunk of non-breaking output text terminated by a hard or soft newline.
/// ...
class Chunk { ... }
考虑 在文档注释中添加示例代码。
/// Returns the lesser of two numbers.
/// ```dart
/// min(5, 3) == 3
/// ```
num min(num a, num b) => ...
人类非常擅长从示例中抽象出实质内容，所以即使提供一行最简单的示例代码都可以让 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 {}
Markdown
文档注释中允许使用大多数 markdown 格式，并且 dartdoc 会根据 markdown package. 进行解析。
有很多指南已经向您介绍Markdown。它普遍受欢迎是我们选择它的原因。这里只是一个简单的例子，让您了解所支持的内容：
/// This is a paragraph of regular text.
/// This sentence has *two* _emphasized_ words (italics) and **two**
/// __strong__ ones (bold).
/// A blank line creates a separate paragraph. It has some `inline code`
/// delimited using backticks.
/// * Unordered lists.
/// * Look like ASCII bullet lists.
/// * You can also use `-` or `+`.
/// 1. Numbered lists.
/// 2. Are, well, numbered.
/// 1. But the values don't matter.
/// * You can nest lists too.
/// * They must be indented at least 4 spaces.
/// * (Well, 5 including the space after `///`.)
/// Code blocks are fenced in triple backticks:
/// ```dart
/// this.code
/// .will
/// .retain(its, formatting);
/// ```
/// The code language (for syntax highlighting) defaults to Dart. You can
/// specify it by putting the name of the language after the opening backticks:
/// ```html
/// <h1>HTML is magical!</h1>
/// ```
/// Links can be:
/// * https://www.just-a-bare-url.com
/// * [with the URL inline](https://google.com)
/// * [or separated out][ref link]
/// [ref link]: https://google.com
/// # A Header
/// ## A subheader
/// ### A subsubheader
/// #### If you need this many levels of headers, you're doing it wrong
避免 过度使用 markdown。
如果有格式缺少的问题，格式化已有的内容来阐明你的想法，而不是替换它，内容才是最重要的。
/// You can use [CodeBlockExample] like this:
/// var example = CodeBlockExample();
/// print(example.isItGreat); // "Yes."
如何写注释
虽然我们认为我们是程序员，但是大部分情况下源代码中的内容都是为了让人类更易于阅读和理解代码。对于任何编程语言，都值得努力练习来提高熟练程度。
This section lists a few guidelines for our docs. You can learn more about
best practices for technical writing, in general, from articles such as
Technical writing style.
推荐 简洁.
要清晰和准确，并且简洁。
