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 對映語法配置 lint 規則，請在 linter > rules 下新增 comment_references: true

linter:
  rules:
    comment_references: true