falconGitHub

comment-references

Same as comment_references in Dart lints

Path
lint/correctness/comment-references
Default
On (recommended)
Origin
Dart lints
Rule
207 of 512
recommended

Flags doc-comment references [name] that resolve to nothing in scope.

dartdoc links a bracketed name to the declaration it denotes, so a misspelled or stale [name] renders as plain text and the link silently breaks. References are parsed and resolved as the analyzer's doc-comment parser and CommentReferenceResolver do (see crate::lint::doc_comments): [name], [Type.member], [prefix.name] and [prefix.Type.member] (including operators) are reported when the last name resolves to nothing; [this], [null], [true] and [false] are always reported. References defined as Markdown link references (/// [name]: https://...), Markdown link text and code spans and blocks are not references. Names falcon cannot prove absent (an unindexed import or supertype) are not reported.

Invalid

example.dartdart
/// Returns [valeu] doubled.
int twice(int value) => value * 2;

/// Wraps a [Strng] for display.
class Label {
  Label(this.text);

  /// The text; never [null].
  final String text;

  /// Renders [text] with [prefx].
  String render(String prefix) => '$prefix$text';

  /// See [Label.missing] for details.
  void describe() {}
}

/// Use [Unknown] instead, or [this].
void legacy() {}

/// Shades of [Colour].
enum Shade {
  /// Brighter than [dakr].
  light,
  dark,
}

/// A typedef's scope is closed: [day] and [T] resolve, [missingName] does not.
typedef DayPredicate<T> = bool Function(DateTime day, T value);

extension type WorkerScope(int value) {
  void onconnect() {}
}

/// The obsolete camel-case event [WorkerScope.onConnect] does not exist.
void listenToWorker() {}
The referenced name `valeu` isn't visible in scope.
1/// Returns [valeu] doubled.
The referenced name `Strng` isn't visible in scope.
3
4/// Wraps a [Strng] for display.
The referenced name `null` isn't visible in scope.
7
8 /// The text; never [null].
The referenced name `prefx` isn't visible in scope.
10
11 /// Renders [text] with [prefx].
The referenced name `Label.missing` isn't visible in scope.
13
14 /// See [Label.missing] for details.
The referenced name `Unknown` isn't visible in scope.
17
18/// Use [Unknown] instead, or [this].
The referenced name `this` isn't visible in scope.
17
18/// Use [Unknown] instead, or [this].
The referenced name `Colour` isn't visible in scope.
20
21/// Shades of [Colour].
The referenced name `dakr` isn't visible in scope.
22enum Shade {
23 /// Brighter than [dakr].
The referenced name `missingName` isn't visible in scope.
27
28/// A typedef's scope is closed: [day] and [T] resolve, [missingName] does not.
The referenced name `WorkerScope.onConnect` isn't visible in scope.
34
35/// The obsolete camel-case event [WorkerScope.onConnect] does not exist.

Valid

example.dartdart
/// Returns [value] doubled, see [Label] and [print].
int twice(int value) => value * 2;

/// A label holding [text]; compare with [Label.render] and [Object].
///
/// Code is not checked: `[notAReference]` and
///
/// ```dart
/// final list = [missing];
/// ```
///
/// Links are not references: [the docs](https://dart.dev) and [guide][].
///
/// [guide]: https://dart.dev/guides
class Label<T> {
  Label(this.text);

  /// The text, typed [T]; equal [hashCode] values for equal [text].
  final String text;

  /// Renders [text] after [prefix] using [twice] and [Shade.dark].
  String render(String prefix) => '$prefix$text';
}

/// Mentions [Shade.values], [index], [light], and [toString].
enum Shade {
  /// Unlike [dark].
  light,
  dark,
}

/// A [FancyLabel] inherits [render] and [text] from [Label].
class FancyLabel extends Label<int> {
  FancyLabel(super.text);
}

/// [List] of [int] values in a [Map], with [Duration] and [identical].
const values = <int>[];

/// Built by [Point.new], [Implicit.new], [Factory.new], [Tone.new],
/// [Wrapper.new], [AbstractBase.new], and [Named.new].
class Point {
  Point(this.x);

  final int x;
}

class Implicit {}

abstract class AbstractBase {}

class Factory {
  Factory._();

  factory Factory.new() => Factory._();
}

enum Tone { low, high }

extension type Wrapper(int value) {}

extension type Named._(int value) {
  Named(int value) : this._(value);
}

/// Extension-type constructors and declared members resolve:
/// [WorkerScope.new], [NamedScope.internal], [WorkerScope.onconnect].
void listenToWorker() {}

extension type WorkerScope(int value) {
  void onconnect() {}
}

extension type NamedScope.internal(int value) {}

Configure comment-references

Set its severity in falcon.json. See the configuration guide.

falcon.jsonjson
{
  "linter": {
    "rules": {
      "correctness": {
        "comment-references": "error"
      }
    }
  }
}

Or silence one occurrence with a suppression comment; the reason is required.

example.dartdart
// falcon-ignore lint/correctness/comment-references: <reason>