ドキュメントコメントの参照

ドキュメントコメントには、さまざまな識別子への参照を含めることができます。関数やクラスなどの要素は、ドキュメントコメント（///で始まるコメント）内で名前を角括弧（[...]）で囲むことで参照できます。いくつかの例

/// Returns a [String].
String f() => 'Hello';

/// Wraps [object] with [Future.value].
Future<T> g<T>(T object) => Future.value(object);

これらのドキュメントコメントには、Stringクラス、objectパラメータ、およびFuture.valueコンストラクタへの参照が含まれています。

ドキュメントコメントの参照でコード要素を参照することには、いくつかの利点があります

ドキュメントコメントの参照により、いくつかのIDE機能が有効になります

• コード補完要素の名前は、角括弧内でコード補完できます。
• リネームリファクタリングIDEコマンドを介して要素の名前が変更されると、IDEはその要素の使用箇所（ドキュメントコメント内の参照を含む）を書き直すことができます。
• 参照の検索IDEが要素のすべての「参照」を一覧表示するとき、ドキュメントコメント内の参照を含めることができます。
• 定義へ移動IDEは、ドキュメントコメント参照の場所で定義へ移動サポートも提供できます。

dart docによって生成されたAPIドキュメントでは、ドキュメントコメントの参照は、可能であれば参照されている要素のドキュメントページにリンクされます。要素にドキュメントページがない場合（たとえば、関数のパラメータ、型パラメータ、またはプライベートクラス）、リンクは作成されません。

ほとんどのライブラリメンバーは、クラス、定数、列挙型、名前付き拡張、拡張型、関数、ミックスイン、および型エイリアスを含む、ドキュメントコメントで参照できます。これには、ローカルで宣言されたもの、インポートされたもの、またはドックインポートでインポートされたものなど、スコープ内のすべてのライブラリメンバーが含まれます。インポートプレフィックスでインポートされたライブラリメンバーは、プレフィックスを使用して参照できます。たとえば

import 'dart:math' as math;

/// [List] is in scope.
/// So is [math.max].
int x = 7;

クラス、列挙型、拡張、拡張型、およびミックスインのほとんどのメンバーも参照できます。スコープ外のメンバーへの参照は、コンテナの名前で修飾（プレフィックス）する必要があります。たとえば、Futureクラスの静的メソッドwaitは、ドキュメントコメントで[Future.wait]として参照できます。これはインスタンスメンバーにも当てはまります。Listクラスのメソッドaddとプロパティlengthは、[List.add]および[List.length]として参照できます。コンテナメンバーがスコープ内にある場合（たとえば、インスタンスメソッドのドキュメントコメント内）、修飾コンテナ名なしで参照できます

abstract class MyList<E> implements List<E> {
  /// Refer to [add] and [contains], which is declared on [Iterable].
  void myMethod() {}
}

名前のないコンストラクタは、名前のないコンストラクタのティアオフと同様に、new名を使用して参照できます。たとえば、[DateTime.new]は、名前のないDateTimeコンストラクタへの参照です。

関数のパラメータと関数型のパラメータは、スコープ内にある場合にのみドキュメントコメントで参照できます。したがって、それらは、そのようなパラメータの関数またはそのエンクロージング関数型の型エイリアスに関するドキュメントコメント内でのみ参照できます。

型パラメータは、スコープ内にある場合にのみドキュメントコメントで参照できます。したがって、メソッド、トップレベル関数、または型エイリアスの型パラメータは、その要素に関するドキュメントコメント内でのみ参照でき、クラス、列挙型、拡張、拡張型、およびミックスインの型パラメータは、その要素に関するドキュメントコメント内またはそのメンバーのいずれかに関するドキュメントコメント内でのみ参照できます。

クラス、列挙型、拡張型、またはミックスインにエイリアスを付ける型エイリアスのドキュメントコメントは、エイリアスされた型のメンバーをスコープ内にあるかのように参照できません。

Dartは@docImportドキュメンテーションタグをサポートしており、これにより、実際にはインポートせずに外部要素をドキュメントコメントで参照できます。このタグは、libraryディレクティブの上にドキュメントコメントで指定できます。たとえば

/// @docImport 'dart:async';
library;

/// Doc comments can now reference elements like
/// [Future] and [Future.value] from `dart:async`,
/// even if the library is not imported with an actual import.
class Foo {}

ドックインポートは、通常のDartインポートと同様のURIスタイルをサポートします。これには、dart:およびpackage:スキーム、および相対パスが含まれます。ただし、遅延させたり、as、show、またはhideで設定したりすることはできません。