comment_references

僅在文件註解中參考作用域內的識別符。

請務必僅在文件註解中參考作用域內的識別符。

如果您將變數、方法或類型名稱等識別符以方括號括起來，那麼您的 IDE 和 dart doc 等工具就可以連結到它們。為了使此功能生效，請確保文件中所有以方括號括起來的識別符都在作用域內。

例如，假設 outOfScopeId 超出作用域

錯誤範例

/// Returns whether [value] is larger than [outOfScopeId].
bool isOutOfRange(int value) { ... }

正確範例

/// Returns the larger of [a] or [b].
int max_int(int a, int b) { ... }

請注意，方括號註解格式旨在允許註解使用相當自然的格式來參考宣告，但不允許任意表達式。特別是，方括號內的程式碼參考可以包含以下任何一項

• 註解作用域內的一個裸識別符（請參閱規格以瞭解文件註解中「作用域內」的定義）。例如 [print] 和 [Future]。
• 兩個以句點分隔的識別符（「帶前綴的識別符」），其中第一個識別符充當命名空間識別符，例如類別屬性名稱或方法名稱，以包含類別的名稱作為前綴，或以匯入前綴作為前綴的頂層識別符。例如 [Future.new]（未命名的建構子）、[Future.value]（建構子）、[Future.wait]（靜態方法）、[Future.then]（實例方法）、[math.max]（假設 'dart:async' 是以 max 前綴匯入）。
• 帶前綴的識別符，後跟一對括號，用於消除具名建構子與實例成員（其名稱允許衝突）之間的歧義。例如 [Future.value()]。
• 三個以兩個句點分隔的識別符，其中第一個識別符是匯入前綴名稱，第二個識別符是頂層元素（如類別或擴展），第三個識別符是該頂層元素的成員。例如 [async.Future.then]（假設 'dart:async' 是以 async 前綴匯入）。

已知限制

comment_references lint 規則與 Dart 分析器的註解參考概念一致，這有時與 Dartdoc 的註解參考概念不同。lint 規則可能會報告 Dartdoc 可以解析但分析器無法解析的註解參考。請參閱 sdk#57783 以取得更多資訊。

若要啟用 comment_references 規則，請在您的 analysis_options.yaml 檔案中的 linter > rules 下新增 comment_references

linter:
  rules:
    - comment_references

如果您改用 YAML map 語法來設定 linter 規則，請在 linter > rules 下新增 comment_references: true

linter:
  rules:
    comment_references: true

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