Dart 注释

Dart 语言一共支持 3 种注释：单行注释、多行注释、文档注释；编译器会忽略注释内普通文本，仅文档注释可用于生成代码文档。

注释的目的，是为了方便程序员查阅代码，了解代码的功能和作用，同时注释页可以让我们临时屏蔽一些代码，用来调试测试程序，查找问题。

文档注释，可以让我们借助工具，生成一个代码的帮助文档。方便我们查阅代码的功能。也方便他人查看我们的代码。

如果你学过其他语言，可以很快就理解注释。 基本和C C++ JAVA C#等这些类C语言差不多。

1、单行注释 //

1. 以 // 开头；
2. 从 // 开始到本行末尾的所有内容都会被 Dart 编译器忽略；
3. 仅作用于当前一行，无法跨行注释。

例子

void main() {
  // TODO: 重构为抽象羊驼问候工厂类？
  print('欢迎来到我的羊驼农场！');
}
Code language: JavaScript (javascript)

2、多行注释 /* */

1. 起始标记 /*，结束标记 */；
2. /* 和 */ 之间所有内容会被编译器忽略（文档注释除外，见下文）；
3. 支持嵌套书写。

例子

void main() {
  /*
   * 饲养羊驼工作量很大，可以考虑养鸡。

  Llama larry = Llama();
  larry.feed();
  larry.exercise();
  larry.clean();
   */
}Code language: Dart (dart)

上面代码，{}里面的所有代码都被注释了，都不会编译，编译器会忽略这部分代码。

3、文档注释

用于生成官方 API 文档，相当于别人使用你的库的时候，可以通过这个API文档查看你写的代码，函数接口，参数等等的使用说明，相当于说明书。

1. 两种书写格式

• 单行文档注释：连续多行 ///，效果等同于多行文档注释 ，注意，是///多了一些斜杠。
• 多行文档注释：/** 开头、*/ 结尾，注意开头的注释 多了一个星号 * 是/**

2. 核心语法规则

1. 文档注释内普通文本会被代码分析器忽略；
2. 方括号 [] 包裹标识符 是特殊语法：可引用类、方法、字段、顶层变量、函数、参数；
3. 方括号内的名称会在当前被注释代码的词法作用域中解析；
4. 生成文档后，[标识符] 会自动变成跳转到对应文档的超链接。

示例

// 单行普通注释：定义饲料类
class Food {
  String type;
  // 单行注释：饲料重量，单位捆
  int baleCount;

  Food(this.type, this.baleCount);
}

/*
多行普通注释：
运动类型枚举，用于羊驼运动方法
支持嵌套注释演示
/* 嵌套内层注释 */
*/
enum Activity {
  walk,
  run,
  graze
}

/// 驯化的南美骆驼科动物（大羊驼，学名Lama glama）
///
/// 在前哥伦布时代，安第斯文明就把羊驼当作肉食与驮运牲畜使用。
///
/// 和其他动物一样羊驼需要进食，记得给它们投喂 [Food] 类型饲料，调用 [feed] 方法。
class Llama {
  String? name;

  /// 给羊驼投喂指定 [food] 饲料
  ///
  /// 一只羊驼每周通常消耗一捆干草。
  void feed(Food food) {
    // 单行注释：打印喂食信息
    print("${name}吃了${food.baleCount}捆${food.type}");
  }

  /// 让羊驼进行 [activity] 运动，持续 [timeLimit] 分钟
  void exercise(Activity activity, int timeLimit) {
    print("${name}进行${activity.name}运动，时长${timeLimit}分钟");
  }
}

void main() {
  // TODO：后续可拓展多只羊驼管理
  Llama larry = Llama();
  larry.name = "拉里";

  // 创建干草饲料
  Food hay = Food("干草", 1);
  larry.feed(hay);

  // 羊驼散步20分钟
  larry.exercise(Activity.walk, 20);
}
Code language: PHP (php)

文档生成后：[feed] 链接到当前类的 feed 方法文档，[Food] 链接到 Food 类文档。

D:\dartdemo\firstdart>dart run
Building package executable...
Built firstdart:firstdart.
拉里吃了1捆干草
拉里进行walk运动，时长20分钟

D:\dartdemo\firstdart>dart doc
Documenting firstdart...
Discovering libraries...
Linking elements...
Precaching local docs for 136851 elements...
Initialized dartdoc with 50 libraries
Generating docs for library firstdart.dart from package:firstdart/firstdart.dart...
Found 0 warnings and 0 errors.
Documented 1 public library in 10.3 seconds
Success! Docs generated into d:\dartdemo\firstdart\doc\apiCode language: JavaScript (javascript)

然后我们项目目录下面，就多了一个doc文件夹，打开后看到

配套工具

1. 文档生成工具：dart doc 作用：解析 Dart 源代码，自动生成 HTML 格式的项目 API 文档；Dart 官方 API 文档就是使用该工具生成。
2. 注释编写规范参考：官方指南《Effective Dart: Documentation》，可查阅规范的注释书写结构与风格。

总结

表格

注释类型	起始符号	跨行能力	支持嵌套	用途
单行注释	//	不支持，仅本行	无	临时单行备注、代码待办
普通多行注释	/* */	支持任意多行	支持嵌套	批量注释大段代码、长说明
文档注释	/// / /** */	支持多行	不建议嵌套	给类 / 方法 / 变量写 API 说明，生成官方文档，支持[]链接标识符