comment_references

ドキュメントコメントでは、スコープ内の識別子のみを参照してください。

このルールは、Dart 2.0から利用可能です。

このルールには、クイックフィックスがあります。

実施する ドキュメントコメントでは、スコープ内の識別子のみを参照してください。

変数、メソッド、型名の識別子を角括弧で囲むと、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]があります。
• ピリオドで区切られた2つの識別子（「接頭辞付き識別子」）。最初の識別子は名前空間識別子として機能し、たとえば、包含クラスの名前を接頭辞としたクラスのプロパティ名やメソッド名、またはインポートプレフィックスを接頭辞としたトップレベルの識別子などがあります。例としては、[Future.new]（名前なしコンストラクタ）、[Future.value]（コンストラクタ）、[Future.wait]（静的メソッド）、[Future.then]（インスタンスメソッド）、[math.max]（'dart:async'がmaxプレフィックスでインポートされている場合）などがあります。
• 接頭辞付き識別子に続く括弧のペア。名前付きコンストラクタとインスタンスメンバー（名前が衝突する可能性があります）を区別するために使用されます。例としては、[Future.value()]などがあります。
• 2つのピリオドで区切られた3つの識別子。最初の識別子はインポートプレフィックス名、2番目の識別子はクラスや拡張のようなトップレベル要素、3番目の識別子はそのトップレベル要素のメンバーです。例としては、[async.Future.then]（'dart:async'がasyncプレフィックスでインポートされている場合）などがあります。

既知の制限事項

comment_references lintルールは、Dartアナライザーのコメント参照の概念に準拠しており、これはDartdocのコメント参照の概念とは時折異なります。アナライザーでは解決できない場合でも、Dartdocが解決できるコメント参照について、lintルールが報告することがあります。詳細については、linter#1142を参照してください。

comment_referencesルールを有効にするには、analysis_options.yamlファイルのlinter > rulesの下にcomment_referencesを追加します。

linter:
  rules:
    - comment_references

特に明記されていない限り、このサイトのドキュメントはDart 3.5.3を反映しています。最終更新日：2024年7月3日。 ソースを表示 または 問題を報告する。