dart-use-doc-examples

Dartdoc での例の使用

目次

• 1. {@example} ディレクティブ
• 2. リージョンの使用
• 3. セットアップコードを非表示にする
• 4. マーカーのフィルタリング規則
• 5. 配置とパスの解決
• 6. 検証

複数行のコード例を含むドキュメントを作成する場合は、通常、それらの例を独立した .dart ファイルに切り出し、/// コメント内に直接記述するのではなく、{@example} ディレクティブを使って挿入してください。こうすることで、例を解析、リント、実行できるようになります。

1. {@example} ディレクティブ

{@example} ディレクティブは外部ファイルを解析し、生成されたドキュメント内のフェンス付き Markdown コードブロックとして展開します。

構文： {@example <path>[#<region>] [lang=LANGUAGE] [indent=keep|strip]}

• <path>：ファイルへのパスです。先頭に / がある場合は、パッケージのルートから評価されます。それ以外の場合は、現在のファイルからの相対パスです。
• lang：Markdown のコードフェンスで使用する言語です。ファイル拡張子から自動検出されます（例：dart）。明示的に指定することもできます（例：lang=text）。
• indent：strip（デフォルト）は、コードブロックの共通の先頭インデントを積極的に削除します。

悪い例（インライン Markdown）：

/// Makes a client service request to the backend.
///
/// ```dart
/// final client = Client();
/// client.send();
/// ```

良い例（外部ファイルの挿入）：

/// Makes a client service request to the backend.
///
/// {@example /example/client_request.dart}

2. リージョンの使用

外部のサンプルファイルには、ドキュメントに表示したくないインポート、セットアップコード、void main() のラッパーが含まれていることがよくあります。{@example} ディレクティブのパスに #<region> を追加し、対象ファイル内でそのコードを #region と #endregion のコメントで囲むと、コードの特定のブロックを抽出できます。

Dart コード（例：/example/client.dart）：

import 'package:http/http.dart';

void main() {
  // #region request_snippet
  final client = Client();
  client.send();
  // #endregion request_snippet
}

Dartdoc での使用方法：

/// Connects the client to the server and sends a request.
///
/// {@example /example/client.dart#request_snippet}

3. セットアップコードを非表示にする

抽出したリージョン内に、コンパイラーやアナライザーを通すために必要でありながら、ドキュメントの読者には無関係（または邪魔）な特定のコード行がある場合は、その行の末尾に #hide を追加してください。

Dart コード：

final mockServer = startServer(); // #hide
final data = await fetch(mockServer.url);

生成されたドキュメントには、final data = await fetch(mockServer.url); のみが表示されます。#hide が付いた行は完全に除外されます。

4. マーカーのフィルタリング規則

#hide、#region、#endregion マーカーを使用する場合は、次の 2 つの技術的な制約に従う必要があります。

• リージョンが必須： マーカーの処理と除去は、特定のリージョン接尾辞（例：{@example file.dart#region_name}）を指定した場合にのみ行われます。リージョン接尾辞を指定せずにファイル全体を挿入すると、// #hide のようなマーカーテキストも含め、ファイルはソースに記述されたとおりに埋め込まれます。
• 形式に依存しない： マーカーシステムは完全に形式に依存しません。Dartdoc はマーカー文字列を含む行を正規表現で除去するだけなので、Dart 以外のファイル（YAML コメント内の # #region や HTML コメント `` など）でも同様に機能します。

5. 配置とパス解決

{@example} ディレクティブはブロックレベルのディレクティブです。/// を前置して、単独の行に記述する必要があります。内部の <path> パーサーは、厳密な URI 参照の規則に従います。

• パッケージルートのパス（/）：先頭にスラッシュがあるパスは、Dart パッケージのルートに直接解決されます。配置先のファイルが深い階層にある場合に使用してください。
  • 例： {@example /test/data/sample.txt} は <package_root>/test/data/sample.txt に正確に対応します。
• 相対パス：先頭にスラッシュがないパスは、ドキュメントコメントを含むファイルのディレクトリを基準に解決されます。
  • 例： {@example ../utils/demo.dart}
• 境界の適用： .. セグメントを使って上位階層へ移動しても問題ありませんが、dartdoc はディレクトリの移動をパッケージルートで停止します（パッケージの外に出ることはありません）。
• ネットワーク URL は使用できません： 絶対 URI（例：https:// で始まる URI）はサポートされていません。サンプルファイルは、ローカルファイルシステム上に置く必要があります。
• 区切り文字とエンコード： dartdoc はパスを URI として解決するため、フォルダーの区切り文字には常にスラッシュ（/）を使用してください（Windows でも同様です）。URI 参照の規則で許可されている URI エンコード文字（スペースを表す %20 など）は、そのまま使用できます。

6. 検証

サンプルを挿入した後、次の操作を行います。

1. サンプルファイルに対して dart analyze を実行し、非表示のセットアップコードがコンパイルされることを確認します。
2. （任意）dart doc を実行し、dartdoc が「Failed to read file」や「missing region」の警告を出さずにディレクティブを正常に解析することを確認します。