文档注释引用

文档注释可以包含对各种标识符的引用。函数和类等元素可以通过在文档注释（以 /// 开头的注释）中将它们的名称用方括号 ([...]) 包围起来进行引用。一些示例：

/// Returns a [String].
String f() => 'Hello';

/// Wraps [object] with [Future.value].
Future<T> g<T>(T object) => Future.value(object);

这些文档注释包含对 String 类、object 参数和 Future.value 构造函数的引用。

使用文档注释引用来引用代码元素有几个好处：

文档注释引用支持以下几个 IDE 功能：

• 代码补全 元素的名称可以在方括号内进行代码补全。
• 重命名重构 当通过 IDE 命令重命名元素时，IDE 可以重写该元素的使用，包括文档注释中的引用。
• 查找引用 当 IDE 列出对某个元素的所有“引用”时，可以包含文档注释中的引用。
• 跳转到定义 IDE 还可以在文档注释引用的位置提供跳转到定义的支持。

在使用 dart doc 生成的 API 文档中，文档注释引用（如果可能）会链接到所引用元素的文档页面。如果该元素没有文档页面（例如，函数参数、类型参数或私有类），则不会创建链接。

大多数库成员可以在文档注释中引用，包括类、常量、枚举、命名扩展、扩展类型、函数、混入和类型别名。这包括所有在作用域内的库成员，无论是本地声明的、导入的，还是通过文档导入导入的。使用导入前缀导入的库成员可以使用该前缀进行引用。例如：

import 'dart:math' as math;

/// [List] is in scope.
/// So is [math.max].
int x = 7;

类、枚举、扩展、扩展类型和混入的大多数成员也可以被引用。对不在作用域内的成员的引用必须用其容器的名称进行限定（加前缀）。例如，可以在文档注释中用 [Future.wait] 引用 Future 类上的静态方法 wait。实例成员也是如此；List 类上的 add 方法和 length 属性可以用 [List.add] 和 [List.length] 引用。当容器成员在作用域内时，例如在实例方法的文档注释中，可以在不使用限定容器名称的情况下进行引用：

abstract class MyList<E> implements List<E> {
  /// Refer to [add] and [contains], which is declared on [Iterable].
  void myMethod() {}
}

可以使用 new 名称引用未命名构造函数，类似于未命名构造函数的 tear-off。例如，[DateTime.new] 是对未命名 DateTime 构造函数的引用。

函数参数和函数类型的参数只有在作用域内时才能在文档注释中被引用。因此，它们只能在其参数所在的函数的文档注释中，或在其参数所在函数类型的类型别名的文档注释中被引用。

类型参数只有在作用域内时才能在文档注释中被引用。因此，方法、顶层函数或类型别名的类型参数只能在该元素的文档注释中被引用，而类、枚举、扩展、扩展类型和混入的类型参数只能在该元素或其成员之一的文档注释中被引用。

别名化类、枚举、扩展类型或混入的类型别名的文档注释不能引用别名化类型的任何成员，就好像它们在作用域内一样。

Dart 支持 @docImport 文档标签，它允许在文档注释中引用外部元素，而无需实际导入它们。此标签可以在 library 指令上方的文档注释中指定。例如：

/// @docImport 'dart:async';
library;

/// Doc comments can now reference elements like
/// [Future] and [Future.value] from `dart:async`,
/// even if the library is not imported with an actual import.
class Foo {}

文档导入支持与 常规 Dart 导入 相同的 URI 样式，包括 dart: 和 package: 方案以及相对路径。但是，它们不能被延迟加载或使用 as、show 或 hide 进行配置。