comment_references

Group: errors

Maturity: stable

Dart SDK: >= 2.0.0 • (Linter v0.1.17)

View the Project on GitHub dart-lang/linter

DO reference only in scope identifiers in doc comments.

If you surround things like variable, method, or type names in square brackets, then dartdoc will look up the name and link to its docs. For this all to work, ensure that all identifiers in docs wrapped in brackets are in scope.

For example,

GOOD:

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

On the other hand, assuming outOfScopeId is out of scope:

BAD:

void f(int outOfScopeId) { ... }

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 either