Flutter学习之Dart语言注释

代码注释是开发过程当中必不可少的一个过程，那么，咱们在进行Flutter开发时，怎么去进行文档注释呢？ 这篇文章的主旨就是Flutter所使用的dart语言注释学习。

Dart支持单行注释, 多行注释和文档注释

1.单行注释

单行注释以//开头， Dart编译器会忽略//和行尾之间的全部内容

say() {
    // TODO: say something
    print('Hello dart!');
  }
复制代码

2.多行注释

多行注释以 /* 开头，以 / 结尾, Dart编译器忽略 / 和 */ 之间的全部内容（除非注释是文档注释）, 多行注释能够嵌套

sayWhat(String what) {
    /* * Say something * */
    print(what);
  }
复制代码

3.文档注释

文档注释是以 ///或 /** 开头的多行或单行注释, 在连续行上使用 /// 与多行文档注释具备相同的效果。

在文档注释中，Dart编译器忽略全部文本，除非它括在括号中。 使用括号，您能够引用类，方法，字段，顶级变量，函数和参数。 括号中的名称在已记录的程序元素的词法范围内获得解析。

/// Dart class
///
/// TODO: Say hello to dart
class Dart {
  /// Say hello to dart
  say() {
    // TODO: say something
    print('Hello dart!');
  }

  /// Say something to dart
  /// The string [what] is what you want to say.
  sayWhat(String what) {
    /* * Say something * */
    print(what);
  }
}
复制代码

Windows10+Flutter环境下咱们使用dart sdk的文档生成工具来生成文档(dartdoc的Github地址)，dartdoc.bat位于

XXX\dart-sdk\bin
复制代码

从Flutter项目的根目录运行dartdoc, 文档目录会根据flutter项目的目录的lib下进行生成

咱们能够看到生成的文档放在了目录

项目目录\doc\api 
复制代码

用浏览器打开自定义类的注解为

4.高效Dart注释

• 注释
• 文档注释
• Markdown
• 写注释

在编写代码时， 很容易认为本身的代码已经写得很清楚，可是没有意识到已经依赖脑海中的上下文，若是另外一我的接手你的代码的话，或者代码写完一段时间后再回顾的话，一段简明扼要的注释是很是重要的，能够节省大量时间，所以下面这里有一些提升dart开发的注释窍门。

• 注释

  注释句子化

  避免使用块注释

• 文档注释

  使用 /// 注释成员和类型

  优先为public的接口编写注释

  考虑写一个库级别的文档注释

  考虑为private的接口编写文档注释

  文档开头尽可能用单句总结

  分离文档注释的第一句到本身的段落中

  避免与周围上下文冗余

  优先使用第三人称动词注释函数或方法

  优先使用名词短语注释变量, getter或setter

  优先使用名词短语注释库或者类型

  考虑使用代码示例注释

  尽可能在文档注释中使用方括号来引用范围内标识符

  尽可能简约地注释参数, 返回值和异常

  尽可能在元数据注释以前加上文档注释

• Markdown 避免过分使用markdown

  避免使用HTML进行格式化

  优先使用反括号来隔开代码块

• 写注释 简短优先

  避免使用缩写词和缩写词

  首选使用“this”而不是“the”来引用成员实例

注释

如下提示适用于你不但愿包含在生成的文档中的注释

注释句子化

// Not if there is nothing before it.
if (_chunks.isEmpty) return false;
复制代码

针对英文：第一个字母需大写，除非它是区分大小写的标识符， 且须要使用句号，或者！或者？结束句子，全部注释都需如此：文档注释，内联内容，甚至是TODO。

中文： 尽可能用一句简明扼要的话注释

避免使用块注释

greet(name) {
  // Assume we have a valid name.
  print('Hi, $name!');
}
复制代码

下面为不推荐示范：

greet(name) {
  /* Assume we have a valid name. */
  print('Hi, $name!');
}
复制代码

推荐使用（/ * ... * /）注释代码，其余文字注释应该使用//

文档注释

文档注释特别方便，由于dartdoc命令能够解析并生成好看的文档页。文档注释是任何出如今声明以前的注释，dartdoc会查找使用 /// 标记的注释

使用 /// 注释成员和类型

Linter规则：slash_for_doc_comments 使用文档注释 /// 而不是常规的注释使执行dartdoc命令时能找到注释并生成文档，通常在方法和类名上注释

/// The number of characters in this chunk when unsplit.
int get length => ...
复制代码

下面为不推荐示范

// The number of characters in this chunk when unsplit.
int get length => ...
复制代码

因为历史缘由，dartdoc支持doc comments的两种语法：///（“C＃style”）和/ ** ... * /（“JavaDoc style”），咱们更喜欢///，由于它更紧凑。 / *和 /将两条无内容行添加到多行文档注释中。 在某些状况下，///语法也更容易阅读，例如当doc注释包含使用*标记列表项的项目符号列表时。

若是您偶然发现仍使用JavaDoc样式的代码，请考虑清理它。

优先为public的接口编写注释

Linter 规则: package_api_docs, public_member_api_docs

没必要记录每一个库，顶级变量，类型和成员，但应该注释其中的大多数。

考虑写一个库级别的文档注释

与Java这样的语言不一样，类是程序组织中的惟一单元，可是在Dart中，库自己就是用户直接使用，导入和思考的实体。 这使得库指令成为文档注释的好地方，能够向读者介绍其中提供的主要概念和功能。 考虑包括：

• 关于库用途的单句摘要。
• 整个库使用的术语解释。
• 一些使用API完成的完整代码示例。
• 连接到(即库中使用的)最重要或最经常使用的类和函数。
• 连接到(即库中使用的)库所关注的域上的外部引用。

你能够经过在文件开头的库指令上方放置doc注释来记录库。 若是库没有库指令，您能够添加一个只是挂起文档注释。

考虑为private的接口编写文档注释

Doc comments aren’t just for external consumers of your library’s public API. They can also be helpful for understanding private members that are called from other parts of the library.

文档注释不只适用于库的公共API， 一样有助于理解从库的其余部分调用的私有成员。

文档开头尽可能用单句总结

开始以句号结尾的简短的，以用户为中心的注释文档。 句子片断一般就足够了，为读者提供足够的上下文来定位本身，并决定是否应该继续阅读或寻找解决问题的方法。

/// Deletes the file at [path] from the file system.
void delete(String path) {
  ...
}
复制代码

下面为不推荐示范：

/// Depending on the state of the file system and the user's permissions, /// certain operations may or may not be possible. If there is no file at /// [path] or it can't be accessed, this function throws either [IOError]
/// or [PermissionError], respectively. Otherwise, this deletes the file.
void delete(String path) {
  ...
}
复制代码

简而言之就是尽可能简明扼要

分离文档注释的第一句到本身的段落中

在第一句以后添加一个空行，将其拆分为本身的段落。 若是多于一句解释是有用的，请将其他部分放在后面的段落中。 这有助于您编写一个简短的第一句话来总结文档。 此外，像Dartdoc这样的工具使用第一段做为类和列表列表等地方的简短摘要。

/// 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) {
  ...
}
复制代码

下面为不推荐示范：

/// 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) {
 ...
}
复制代码

简而言之即第一行说明该方法或类的主要功能，而后空一行，在进行详细描述或者参数等解释

避免与周围上下文冗余

读者能够从文档注释中清楚地看到类的名称，它实现的接口等。当读到成员的文档注释时，签名就在那里，而封闭的类是显而易见的。 这些都不须要在文档注释中拼写出来。 相反，专一于解释读者不知道的内容。

class RadioButtonWidget extends Widget {
 /// Sets the tooltip to [lines], which should have been word wrapped using
 /// the current font.
 void tooltip(List<String> lines) {
   ...
 }
}
复制代码

下面为不推荐示范：

class RadioButtonWidget extends Widget {
  /// Sets the tooltip for this radio button widget to the list of strings in
  /// [lines].
  void tooltip(List<String> lines) {
    ...
  }
}
复制代码

上面第一段注释清除地说明了该函数的使用目的，而下面不推荐的示例，则与上下文冗余了，"for this radio button widget"。

优先使用第三人称动词注释函数或方法

文档注释应该关注代码的做用

/// Returns `true` if every element satisfies the [predicate].
bool all(bool predicate(T element)) => ...

/// Starts the stopwatch if not already running.
void start() {
  ...
}
复制代码

优先使用名词短语注释变量, getter或setter

文档注释应该强调属性是什么， 即便对于可能进行计算或其余工做的也是如此。 读者应该关心的是这段代码的结果，而不是代码自己。

/// The current day of the week, where `0` is Sunday.
int weekday;

/// The number of checked buttons on the page.
int get checkedCount => ...
复制代码

优先使用名词短语注释库或者类型

类的文档注释一般是程序中最重要的部分，它们描述了类型的不变性，创建了它使用的术语，并为类的成员提供了其余文档注释的上下文，在这里作一点额外的努力可让其余成员更容易记录

/// 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更容易学习

######尽可能在文档注释中使用方括号来引用范围内标识符。 Linter规则: comment_references 若是在方括号中包含变量，方法或类型名称等内容，则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 ...
复制代码

尽可能简约地注释参数, 返回值和异常

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) => ...
复制代码

下面为不推荐示范： 其余语言使用详细标记和部分来描述方法的参数和返回值。

/// 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) => ...
复制代码

好吧，做为一个常年使用java开发的中国Androider, 我更偏向于使用第二种方式

尽可能在元数据注释以前加上文档注释

/// 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包相应地处理它。 下面为一个使用示例

/// 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: /// /// ``` /// 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: /// /// * http://www.just-a-bare-url.com /// * [with the URL inline](http://google.com) /// * [or separated out][ref link] /// /// [ref link]: http://google.com /// /// # A Header /// /// ## A subheader /// /// ### A subsubheader /// /// #### If you need this many levels of headers, you're doing it wrong
复制代码

能够看到使用了不少markdown语法注释

避免过分使用markdown

若有疑问，请格式化。 存在格式化以阐明您的内容，而不是替换它。 words很重要

避免使用HTML进行格式化

在极少数状况下使用它可能颇有用，例如表格，但在几乎全部状况下，若是它在Markdown中过于复杂，你最好不要表达它。

优先使用反括号来隔开代码块

Markdown有两种表示代码块的方法：在每行上压缩代码四个空格，或者用反引号code表示。 当在缩进已经有意义的Markdown列表或代码块自己包含缩进代码的内容中使用时，前一种语法很脆弱，意思就是使用markdown注释时，前面已经使用了缩进，可是如今再使用缩进表示代码的话，会显得很差阅读

反引号语法避免了那些缩进问题，让您指出代码的语言，而且与使用内联代码的反引号一致。

/// You can use [CodeBlockExample] like this:
///
/// ```
/// var example = CodeBlockExample();
/// print(example.isItGreat); // "Yes."
/// ```
复制代码

下面为不推荐示范：

/// You can use [CodeBlockExample] like this:
///
///     var example = CodeBlockExample();
///     print(example.isItGreat); // "Yes."
复制代码

这里总结一下什么状况使用markdown注释比较好： 1.注释类时，该类功能须要目录说明 2.示例代码比较多的时候 3.须要列表说明功能的时候

写注释

在开始写注释的时候，不管咱们使用的是中文仍是英文，我以为都得有一个写注释的习惯，由于这关系到之后的我的代码回顾，和别人阅读你的代码的时候的难易程度。

简短优先

要清晰准确，但也要简洁。

避免使用缩写词和缩写词

对于英文来讲：许多人不知道“ie”，“eg”和“et al”是什么意思，你确信你所在领域的每一个人都知道这个首字母缩略词可能并不像你想象的那么广为人知

对于中文来讲：我的以为缩写词应该会用得比较少

首选使用“this”而不是“the”来引用成员实例

记录类的成员时，一般须要返回调用该成员的对象，使用“the”可能含糊不清

class Box {
  /// The value this wraps.
  var _value;

  /// True if this box contains a value.
  bool get hasValue => _value != null;
}
复制代码

Dart语言之旅：www.dartlang.org/guides/lang…