目录

文档注释引用

目录

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

dart
/// 返回一个 [String]。
String f() => 'Hello';

/// 用 [Future.value] 包装 [object]。
Future<T> g<T>(T object) => Future.value(object);

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

引用的特性

#

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

编辑器支持

#

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

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

API 文档

#

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

可以引用什么

#

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

dart
import 'dart:math' as math;

/// [List] 在作用域内。
/// [math.max] 也在作用域内。
int x = 7;

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

dart
abstract class MyList<E> implements List<E> {
  /// 引用 [add] 和 [contains]，它们在 [Iterable] 上声明。
  void myMethod() {}
}

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

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

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

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

除非另有说明，否则本网站上的文档反映的是 Dart 3.6.0。页面最后更新于 2025-02-05。 查看源代码 或 报告问题.