文件註解參考

文件註解可以包含對各種識別符的參考。元素，例如函式和類別，可以透過將其名稱包在方括號 ([...]) 中，在文件註解（以 /// 開頭的註解）中被參考。一些範例

/// 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 文件中，文件註解參考會連結到被參考元素的文件頁面（如果可能）。如果元素沒有文件頁面（例如，函式參數、類型參數或私有類別），則不會建立連結。

大多數程式庫成員都可以在文件註解中被參考，包括類別、常數、列舉、具名擴充、擴充類型、函式、mixins 和類型別名。這包括所有在範圍內的程式庫成員，無論是本地宣告還是匯入的。使用匯入前綴匯入的程式庫成員可以使用前綴進行參考。例如

import 'dart:math' as math;

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

類別、列舉、擴充、擴充類型和 mixin 的大多數成員也可以被參考。對不在範圍內的成員的參考必須以其容器名稱作為限定詞（前綴）。例如，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 建構子的參考。

函式的參數和函式類型的參數只能在其範圍內的文件註解中被參考。因此，它們只能在這種參數的函式的文件註解中或在這種參數的封閉函式類型的類型別名中被參考。

類型參數只能在其範圍內的文件註解中被參考。因此，方法、頂層函式或類型別名的類型參數只能在該元素的文件註解中被參考，而類別、列舉、擴充、擴充類型和 mixin 的類型參數只能在該元素或其成員之一的文件註解中被參考。

別名類別、列舉、擴充類型或 mixin 的類型別名的文件註解不能參考任何別名類型的成員，就好像它們在範圍內一樣。

除非另有說明，否則本網站上的文件反映 Dart 3.7.1。頁面最後更新於 2024-10-10。 檢視原始碼 或 回報問題。