文档注释引用

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

/// 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 名称引用，类似于未命名构造函数的拆分。例如，[DateTime.new] 是对未命名的 DateTime 构造函数的引用。

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

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

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

除非另有说明，否则本网站上的文档反映了 Dart 3.7.1 版本。页面上次更新于 2024-10-10。 查看源代码 或 报告问题。