comment_references

僅在文件註解中參考在範圍內的識別碼。

此規則自 Dart 2.0 起可用。

此規則具有可用的快速修正。

請務必僅在文件註解中參考在範圍內的識別碼。

如果您將變數、方法或類型名稱等識別碼放在方括號中，則您的 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 可以解析的註解引用，即使分析器無法解析。有關更多資訊，請參閱 linter#1142。

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

linter:
  rules:
    - comment_references

除非另有說明，否則本網站上的文件反映的是 Dart 3.6.0。頁面最後更新於 2024-07-03。 檢視來源 或 回報問題。