dart-documentation

Dart コードのドキュメント作成

目次

• 基本原則
• ドキュメントコメントの書式
• 特定の構文のドキュメント作成
• ワークフロー：ドキュメントの生成と検証
• 例

基本原則

• /// のみを使用する： メンバーと型のドキュメントには /// を使用します。ドキュメント作成に /** ... */ ブロックコメントは決して使用しないでください。
• 内部コメントには // を使用する： 生成される公開ドキュメントに表示すべきでない実装の詳細には、標準の // コメントを使用します。
• 文として書式設定する： 最初の単語は大文字で始め（大文字と小文字が区別される識別子を除く）、ピリオドで終わります。
• 簡潔さを優先する： 明確で正確、簡潔な表現にします。メソッドのシグネチャやクラス名から推測できる冗長な情報は避けます。
• Markdown を使用する： 標準の Markdown で書式設定します。コードブロックにはインデントよりバッククォートのフェンス（```）を優先します。HTML タグは避けます。

ドキュメントコメントの書式

• 要約から始める： 最初の文は、簡潔な三人称単数の要約から始めます。
• 要約を独立させる： 要約は独立した行に記述し、その後に空行を入れます。これにより、IDE のツールチップや生成される要約の可読性が向上します。
• 参照には角括弧を使用する： スコープ内の型、メソッド、変数には [identifier] を使用してリンクします。
  • 特定のメンバーには [ClassName.memberName] を使用します。
  • 名前のないコンストラクターには [ClassName.new] を使用します。
• パラメーターと戻り値は文章で説明する： パラメーター、戻り値、例外の説明は、冗長なタグ（例：@param）を使わず、本文に含めます。パラメーターは角括弧で示します。
• メタデータより前に配置する： ドキュメントコメントは必ずメタデータ注釈（例：@override）より前に配置します。

特定の構文のドキュメント作成

メソッドと関数

• 副作用： 主な目的が副作用である場合は、要約を三人称の動詞（例：「サーバーに接続します...」）で始めます。
• 戻り値： 主な目的が値を返すことである場合は、名詞句（例：「[index] 番目の要素...」）で始めます。

変数とプロパティ

• ブール値以外： プロパティが「何であるか」を説明する名詞句で始めます（例：「現在の曜日...」）。
• ブール値： 「Whether」に続けて、名詞句または動名詞句を記述します（例：「モーダルが現在表示されているかどうか...」）。
• ゲッター／セッター： プロパティにゲッターとセッターの両方がある場合は、ゲッターのみをドキュメント化します。

クラスとライブラリ

• クラス： その型のインスタンスを説明する名詞句で始めます。
• ライブラリ： library ディレクティブの前に /// コメントを配置します。1 文の要約、用語の説明、コードサンプルを含めます。

ワークフロー：ドキュメントの生成と検証

Dart パッケージのドキュメントを作成および検証する際は、次のワークフローに従います。

タスクの進捗

• 1. /// と Markdown を使用してドキュメントコメントを記述する。
• 2. 依存関係を解決する：dart pub get を実行する。
• 3. コードにエラーがないことを確認する：dart analyze を実行する。
• 4. ドキュメントを生成して検証する：dart doc --validate-links を実行する。
• 5. 参照の欠落や書式に関する警告がないか、出力を確認する。
• 6. （任意）UI の表示を確認するため、ローカルで配信する。

フィードバックループ：検証

ドキュメントを生成する際は、すべての [references] が正しく解決されることを検証する必要があります。

1. 検証ツールを実行する： dart doc --validate-links . を実行します。
2. エラーを確認する： コンソール出力で、リンク切れや解決されていないシンボルを確認します。
3. 修正する： [brackets] 内の誤字を直し、参照先のメンバーがスコープ内にあることを確認するか、インポートを調整します。警告なしでコマンドが成功するまで繰り返します。

条件ロジック：ドキュメントをローカルで表示する

• 生成された HTML をプレビューする場合：
  1. ローカルサーバーを有効化します：dart pub global activate dhttpd
  2. doc/api ディレクトリを公開します：dart pub global run dhttpd --path doc/api
  3. 表示された localhost の URL をブラウザーで開きます。

例

高品質なメソッドのドキュメント

/// Deletes the file at [path].
///
/// Throws an [IOError] if the file could not be found. Throws a
/// [PermissionError] if the file is present but could not be deleted.
void delete(String path) {
  // Implementation details...
}

高品質なプロパティのドキュメント

/// The pH level of the water in the pool.
///
/// Ranges from 0-14, representing acidic to basic, with 7 being neutral.
int get phLevel => _phLevel;
set phLevel(int level) => _phLevel = level;

高品質なブール値のドキュメント

/// Whether the modal should confirm the user's intent on navigation.
bool get shouldConfirm => _shouldConfirm;

コードサンプル付きの高品質なクラスのドキュメント

/// The lesser of two numbers.
///
/// ```dart
/// min(5, 3) == 3
/// ```
num min(num a, num b) => (a < b) ? a : b;