comment_references

Only reference in-scope identifiers in doc comments.

此规则自 Dart 2.0 版本起可用。

此规则提供 快速修复 。

DO reference only in-scope identifiers in doc comments.

If you surround identifiers like variable, method, or type names in square brackets, then tools like your IDE and dart doc can link to them. For this to work, ensure that all identifiers in docs wrapped in brackets are in scope.

For example, assuming outOfScopeId is out of scope:

BAD:

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

GOOD:

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

Note that the square bracket comment format is designed to allow comments to refer to declarations using a fairly natural format but does not allow arbitrary expressions. In particular, code references within square brackets can consist of any of the following:

• A bare identifier which is in-scope for the comment (see the spec for what is "in-scope" in doc comments). Examples include [print] and [Future].
• Two identifiers separated by a period (a "prefixed identifier"), such that the first identifier acts as a namespacing identifier, such as a class property name or method name prefixed by the containing class's name, or a top-level identifier prefixed by an import prefix. Examples include [Future.new] (an unnamed constructor), [Future.value] (a constructor), [Future.wait] (a static method), [Future.then] (an instance method), [math.max] (given that 'dart:async' is imported with a max prefix).
• A prefixed identifier followed by a pair of parentheses, used to disambiguate named constructors from instance members (whose names are allowed to collide). Examples include [Future.value()].
• Three identifiers separated by two periods, such that the first identifier is an import prefix name, the second identifier is a top-level element like a class or an extension, and the third identifier is a member of that top-level element. Examples include [async.Future.then] (given that 'dart:async' is imported with an async prefix).

Known limitations

The comment_references lint rule aligns with the Dart analyzer's notion of comment references, which is occasionally distinct from Dartdoc's notion of comment references. The lint rule may report comment references which Dartdoc can resolve, even though the analyzer cannot. See linter#1142 for more information.

要启用 comment_references 规则，请在你的 analysis_options.yaml 文件中，在 linter > rules 下添加 comment_references ：

linter:
  rules:
    - comment_references

除非另有说明，否则本网站上的文档反映的是 Dart 3.6.0。页面最后更新于 2025-02-05。 查看源代码 或 报告问题.