comment_references

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

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

変数、メソッド、型名などの識別子を角括弧で囲むと、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 リンタルールは、Dart アナライザーのコメント参照の概念に沿っており、これは Dartdoc のコメント参照の概念とは時々異なります。アナライザーが解決できないコメント参照であっても、リンタルールが報告する可能性があります。詳細については、sdk#57783 を参照してください。

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

linter:
  rules:
    - comment_references

代わりに YAML マップ構文を使用してリンタルールを構成している場合は、linter > rules の下に comment_references: true を追加します。

linter:
  rules:
    comment_references: true