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 映射语法来配置 linter 规则，请在 linter > rules 下添加 comment_references: true

linter:
  rules:
    comment_references: true

除非另有说明，否则本网站上的文档反映了 Dart 3.7.1 版本。 页面最后更新于 2025-03-07。 查看源代码 或报告问题。