跳到主要内容

comment_references

稳定
有修复方法

在文档注释中仅引用作用域内的标识符。

详情

#

务必在文档注释中仅引用作用域内的标识符。

如果您将变量、方法或类型名称等标识符用方括号括起来,那么您的 IDE 和 dart doc 等工具可以链接到它们。为此,请确保文档中所有用方括号括起来的标识符都在作用域内。

例如,假设 outOfScopeId 超出了作用域

错误示例

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

正确示例

dart
/// 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

analysis_options.yaml
yaml
linter:
  rules:
    - comment_references

如果您改为使用 YAML 映射语法配置 lint 规则,请在 linter > rules 下添加 comment_references: true

analysis_options.yaml
yaml
linter:
  rules:
    comment_references: true