文件註釋引用

文件註釋可以包含對各種識別符號的引用。函式和類等元素可以透過在文件註釋（以 /// 開頭的註釋）中將它們的名稱用方括號 ([...]) 包圍起來進行引用。一些示例：

/// 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 進行配置。