高效 Dart 语言指南：文档

你可能没有意识到，今天你很容易想出来的代码，有多么依赖你当时思路。人们不熟悉你的代码，甚至你也忘记了当时代码功能中有这样的思路。简明，扼要的注释只需花费几秒钟的时间去写，但可以让每个这样的人节约几个小时。

我们知道代码应该子文档（self-documenting），并不是所有的注释都是有用的。但实际情况是，我们大多数人都没有写出尽可能多的评论。和练习一样：从技术上你可以做很多，但是实际上你只做了一点点。尝试着逐步提高。

注释

下面的提示适用于不被生成在文档中的注释。

要 像句子一样来格式化注释。

  1. // Not if there is nothing before it.
  2. if (_chunks.isEmpty) return false;

如果第一个单词不是大小写相关的标识符，则首字母要大写。使用句号，叹号或者问号结尾。所有的注释都应该这样：文档注释，单行注释，甚至 TODO。即使它是一个句子的片段。

不要 使用块注释作用作解释说明。

  1. greet(name) {
  2.   // Assume we have a valid name.
  3.   print('Hi, $name!');
  4. }
  1. greet(name) {
  2.   /* Assume we have a valid name. */
  3.   print('Hi, $name!');
  4. }

可以使用块注释 (/ … /) 来临时的注释掉一段代码，但是其他的所有注释都应该使用 //。

文档注释

文档注释特别有用，应为通过 dartdoc 解析这些注释可以生成 漂亮的文档网页。文档注释包括所有出现在声明之前并使用 /// 语法的注释，这些注释使用使用 dartdoc 检索。

要 使用 /// 文档注释来注释成员和类型。

Linter rule: slash_for_doc_comments

使用文档注释可以让 dartdoc 来为你生成代码 API 文档。 

  1. /// The number of characters in this chunk when unsplit.
  2. int get length => ...
  1. // The number of characters in this chunk when unsplit.
  2. int get length => ...

由于历史原因，dartdoc 支持两种格式的文档注释：/// (“C# 格式”) 和 / … */ (“JavaDoc 格式”)。我们推荐使用 /// 是因为其更加简洁。/ 和 */ 在多行注释中间添加了开头和结尾的两行多余内容。/// 在一些情况下也更加易于阅读，例如，当文档注释中包含有使用 * 标记的列表内容的时候。

如果你现在还在使用 JavaDoc 风格格式，请考虑使用新的格式。

推荐 为公开发布的 API 编写文档注释。

Linter rules: package_api_docs,public_member_api_docs

不必为所有独立的库，顶级变量，类型以及成员编写文档注释。但是它们大多数应该有文档注释。

考虑 编写库级别（library-level）的文档注释。

与Java等类似的语言不同，Java 中类是程序组织的唯一单元。在 Dart 中，库本身就是一个实体，用户可以直接使用，导入及构思它。这使得库成为一个展示文档的好地方。这样可以向读者介绍其中提供的主要概念和功能。其中可以考虑包括下列内容：

  • 关于库用途的单句摘要。

  • 解释库中用到的术语。

  • 一些配合 API 的示例代码。

  • 最重要和最常用的类和函数的链接。

  • 和库相关领域的外部链接。

你可以通过在文件开头的 library 的上方放置 doc 注释来文档注释一个库。如果库没有 library 指令，您可以添加一个，只是挂起 doc 注释。

推荐 为私有API 编写文档注释。

文档注释不仅仅适用于外部用户使用你库的公开 API.它也同样有助于理解那些私有成员，这些私有成员会被库的其他部分调用。

要 要在文档注释开头有一个单句总结。

注释文档要以一个以用户为中心，简要的描述作为开始。通常句子片段就足够了。为读者提供足够的上下文来定位自己，并决定是否应该继续阅读，或寻找其他解决问题的方法。 

  1. /// Deletes the file at [path] from the file system.
  2. void delete(String path) {
  3.   ...
  4. }
  1. /// Depending on the state of the file system and the user's permissions,
  2. /// certain operations may or may not be possible. If there is no file at
  3. /// [path] or it can't be accessed, this function throws either [IOError]
  4. /// or [PermissionError], respectively. Otherwise, this deletes the file.
  5. void delete(String path) {
  6.   ...
  7. }

要 让文档注释的第一句从段落中分开。

在第一句之后添加一个空行，将其拆分为自己的段落。如果不止一个解释句子有用，请将其余部分放在后面的段落中。

这有助于您编写一个紧凑的第一句话来总结文档。此外，像Dartdoc这样的工具使用第一段作为类和类成员列表等地方的简短摘要。 

  1. /// Deletes the file at [path].
  2. ///
  3. /// Throws an [IOError] if the file could not be found. Throws a
  4. /// [PermissionError] if the file is present but could not be deleted.
  5. void delete(String path) {
  6.   ...
  7. }
  1. /// Deletes the file at [path]. Throws an [IOError] if the file could not
  2. /// be found. Throws a [PermissionError] if the file is present but could
  3. /// not be deleted.
  4. void delete(String path) {
  5.   ...
  6. }

避免 与周围上下文冗余。

阅读类的文档注释的可以清楚地看到类的名称，它实现的接口等等。当读取成员的文档时，命名和封装它的类是显而易见的。这些都不需要写在文档注释中。相反，应该专注于解释读者所不知道的内容。 

  1. class RadioButtonWidget extends Widget {
  2.   /// Sets the tooltip to [lines], which should have been word wrapped using
  3.   /// the current font.
  4.   void tooltip(List<String> lines) {
  5.     ...
  6.   }
  7. }
  1. class RadioButtonWidget extends Widget {
  2.   /// Sets the tooltip for this radio button widget to the list of strings in
  3.   /// [lines].
  4.   void tooltip(List<String> lines) {
  5.     ...
  6.   }
  7. }

推荐 用第三人称来开始函数或者方法的文档注释。

注释应该关注于代码 所实现的 功能。 

  1. /// Returns `true` if every element satisfies the [predicate].
  2. bool all(bool predicate(T element)) => ...
  3.  
  4. /// Starts the stopwatch if not already running.
  5. void start() {
  6.   ...
  7. }

推荐 使用名词短语来开始变量、getter、setter 的注释。

注释文档应该表述这个属性是什么。虽然 getter 函数会做些计算，但是也要求这样，调用者关心的是其结果而不是如何计算的。 

  1. /// The current day of the week, where `0` is Sunday.
  2. int weekday;
  3.  
  4. /// The number of checked buttons on the page.
  5. int get checkedCount => ...

避免同时为 setter 和 getter 加文档注释，DartDoc 只会展示其中一个（getter上的文档注释）。

推荐 使用名词短语来开始库和类型注释。

在程序中，类的注释通常是最重要的文档。类的注释描述了类型的不变性、介绍其使用的术语、提供类成员使用的上下文信息。为类提供一些注释可以让其他类成员的注释更易于理解和编写。 

  1. /// A chunk of non-breaking output text terminated by a hard or soft newline.
  2. ///
  3. /// ...
  4. class Chunk { ... }

考虑 在文档注释中添加示例代码。

  1. /// Returns the lesser of two numbers.
  2. ///
  3. /// ```dart
  4. /// min(5, 3) == 3
  5. /// ```
  6. num min(num a, num b) => ...

人类非常擅长从示例中抽象出实质内容，所以即使提供一行最简单的示例代码都可以让 API 更易于理解。

要 使用方括号在文档注释中引用作用域内的标识符。

Linter rule: comment_references

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

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

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

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

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

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

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

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

  1. /// Defines a flag with the given name and abbreviation.
  2. ///
  3. /// @param name The name of the flag.
  4. /// @param abbr The abbreviation for the flag.
  5. /// @returns The new flag.
  6. /// @throws ArgumentError If there is already an option with
  7. ///     the given name or abbreviation.
  8. Flag addFlag(String name, String abbr) => ...

The convention in Dart is to integrate that into the description of the methodand highlight parameters using square brackets. 

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

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

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

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

Markdown

文档注释中允许使用大多数 markdown 格式，并且 dartdoc 会更具 [markdown package][] 进行解析。

有很多指南已经向您介绍Markdown。它普遍受欢迎是我们选择它的原因。这里只是一个简单的例子，让您了解所支持的内容： 

  1. /// This is a paragraph of regular text.
  2. ///
  3. /// This sentence has *two* _emphasized_ words (italics) and **two**
  4. /// __strong__ ones (bold).
  5. ///
  6. /// A blank line creates a separate paragraph. It has some `inline code`
  7. /// delimited using backticks.
  8. ///
  9. /// * Unordered lists.
  10. /// * Look like ASCII bullet lists.
  11. /// * You can also use `-` or `+`.
  12. ///
  13. /// 1. Numbered lists.
  14. /// 2. Are, well, numbered.
  15. /// 1. But the values don't matter.
  16. ///
  17. ///     * You can nest lists too.
  18. ///     * They must be indented at least 4 spaces.
  19. ///     * (Well, 5 including the space after `///`.)
  20. ///
  21. /// Code blocks are fenced in triple backticks:
  22. ///
  23. /// ```
  24. /// this.code
  25. ///     .will
  26. ///     .retain(its, formatting);
  27. /// ```
  28. ///
  29. /// The code language (for syntax highlighting) defaults to Dart. You can
  30. /// specify it by putting the name of the language after the opening backticks:
  31. ///
  32. /// ```html
  33. /// <h1>HTML is magical!</h1>
  34. /// ```
  35. ///
  36. /// Links can be:
  37. ///
  38. /// * https://www.just-a-bare-url.com
  39. /// * [with the URL inline](https://google.com)
  40. /// * [or separated out][ref link]
  41. ///
  42. /// [ref link]: https://google.com
  43. ///
  44. /// # A Header
  45. ///
  46. /// ## A subheader
  47. ///
  48. /// ### A subsubheader
  49. ///
  50. /// #### If you need this many levels of headers, you're doing it wrong

避免 过度使用 markdown。

如果有格式缺少的问题，格式化已有的内容来阐明你的想法，而不是替换它，内容才是最重要的。

避免 使用 HTML 来格式化文字。

例如表格，在极少数情况下它可能很有用。但几乎所有的情况下，在 Markdown 中表格的表示都非常复杂。这种情况下最好不要使用表格。

推荐 使用反引号标注代码。

Markdown 有两种方式来标注一块代码：每行代码缩进4个空格，或者在代码上下各标注三个反引号。当缩进已经包含其他意义，或者代码段自身就包含缩进时，在 Markdown 中使用前一种语法就显得很脆弱。

反引号语法避免了那些缩进的问题，而且能够指出代码的语言类型，内联代码同样可以使用反引号标注。

  1. /// You can use [CodeBlockExample] like this:
  2. ///
  3. /// ```
  4. /// var example = CodeBlockExample();
  5. /// print(example.isItGreat); // "Yes."
  6. /// ```
  1. /// You can use [CodeBlockExample] like this:
  2. ///
  3. ///     var example = CodeBlockExample();
  4. ///     print(example.isItGreat); // "Yes."

如何写注释

虽然我们认为我们是程序员，但是大部分情况下源代码中的内容都是为了让人类更易于阅读和理解代码。对于任何编程语言，都值得努力练习来提高熟练程度。

This section lists a few guidelines for our docs. You can learn more aboutbest practices for technical writing, in general, from articles such asTechnical writing style.

推荐 简洁.

要清晰和准确，并且简洁。

避免 缩写和首字母缩写词，除非很常见。

很多人都不知道 “i.e.”、 “e.g.” 和 “et. al.” 的意思。你所在领域的首字母缩略词对于其他人可能并不了解。

推荐 使用 “this” 而不是 “the” 来引用实例成员。

注释中提及到类的成员，通常是指被调用的对象实例的成员。使用 “the” 可能会导致混淆。 

  1. class Box {
  2.   /// The value this wraps.
  3.   var _value;
  4.  
  5.   /// True if this box contains a value.
  6.   bool get hasValue => _value != null;
  7. }