dart-write-documentation

Dart API ドキュメントの作成

目次

• 1. 範囲と構成
• 2. 文体と書き出し
• 3. 厳格なアンチパターン（禁止事項）
• 4. 技術的な配置と解決
• 5. リンクと Markdown
• 6. 検証
• 例

Dart コードのドキュメントの作成または更新を依頼された場合は、「Effective Dart: Documentation」のガイドラインに基づく以下の書式ルールを厳守してください。

1. 範囲と構成

• 公開 API を対象にする： ドキュメント作成では公開宣言に重点を置きます。明示的に指示された場合を除き、アンダースコア _ で始まるプライベートメンバーはドキュメント化しないでください。生成される API リファレンスサイトには表示されません。
• 必ず /// を使う： すべての API ドキュメントに、連続した行コメント /// を使います。ブロックコメント /** ... */ は使用しないでください。
• 適切な文にする： すべてのコメントを適切な文として記述します。最初の単語（小文字の識別子を除く）は大文字で始め、ピリオドで終えます。
• 最初の段落： ドキュメントコメントの最初の段落は、要素の概要を説明する簡潔な一文にします。ピリオドで終えてください。dartdoc は、一覧表示のためにこの文をそのまま抽出します。
• 区切り： 最初の文の要約と残りのドキュメントの間には、/// を含む空行を必ず入れます。ドキュメントコメントブロックを終了させるため、完全に空の改行（例：/// を含まない \n）は出力しないでください。

2. 文体と書き出し

• プロパティには名詞句を使う： 変数、ゲッター、セッターの説明は名詞句で始めます。 /// 球体の半径。（「半径を取得します」ではありません）
• ブール値には「かどうか」を使う： ブール型プロパティのドキュメントは「かどうか」で始めます。 /// 接続がアクティブかどうか。
• メソッドには三人称の動詞を使う： メソッドや関数の説明は、その動作を示す三人称の動詞で始めます。 /// データベースを初期化します。（「初期化する」や「このメソッドは初期化します」ではありません）
• 冗長な表現を避ける： シグネチャや要素名を繰り返さないでください。「このクラスは……です」や「foo メソッドは……します」と書かないでください。

3. 厳格なアンチパターン（禁止事項）

• Javadoc／TSDoc タグ（@param、@return、@throws など）は使わない： Javadoc 形式のタグ（@param、@return、@returns、@throws、@exception、@see、@type）は使用しないでください。パラメーター名、戻り値の動作、例外については、文章に織り込んでください。

4. 技術的な配置と解決

• アノテーション（@override など）： ドキュメントコメントはメタデータアノテーションの前に配置します。
• 継承されるドキュメント： スーパークラスまたはインターフェースと動作が異ならない場合、@override メンバーにドキュメントコメントを重複して記述しないでください。dartdoc は基底クラスのドキュメントを自動的に継承します。
• ゲッター／セッターの組み合わせ： プロパティにゲッターとセッターの両方がある場合、ドキュメントはゲッターにのみ記述します。両方に記述すると、ツールから警告が出ます。
• デフォルトコンストラクター： ドキュメントコメントから名前のないデフォルトコンストラクターにリンクするには、.new 構文（例：[ClassName.new]）を使用する必要があります。

5. リンクと Markdown

• スコープ内のシンボルには角括弧（[identifier]）を使用する： dartdoc が解決できるよう、スコープ内の識別子（パラメーター、クラス、メソッド、フィールド、トップレベル関数）には角括弧を使ってリンクします。パラメーターにバッククォートを使用しないでください。
• メソッドリンクには括弧を含めない： リンクに括弧を含めないでください（例：[String.contains()] ではなく [String.contains] を使用します）。
• キーワードとリテラルにはバッククォートを使用する： キーワード、リテラル、任意の式はバッククォートで囲みます（例：`null`、`true`、`void`）。キーワードを角括弧で囲まないでください（[null] や [true] は使用しないでください）。
• スコープ外のリンク： 現在のライブラリにインポートされていないシンボルにリンクする必要がある場合は、標準の import を追加するのではなく、ファイルの先頭（library; 宣言上）に @docImport ディレクティブを使用します。
• コードブロック： コードサンプルでは、必ずフェンスに言語を指定します。Dart には ```dart、シェルコマンドには ```sh を使用します。コードブロックの言語を指定しないと、Dartdoc が自動検出を試み、多くの場合誤った言語を判定します。
• 書式設定： 最初の段落の後は、標準的な Markdown（太字、リストなど）を使用して、エッジケース、スローされる例外、呼び出し元からは見えない内部動作を十分に説明します。

6. 検証

ドキュメントコメントを作成または更新した後：

1. dart analyze を実行し、comment_references 警告を発生させずに、角括弧で囲まれた参照がすべて正しく解決されることを確認します。
2. （任意）dart doc を実行し、生成されたドキュメントが正しく表示されることを確認します。

例

1. 禁止タグと文章

悪い例：

/// This method fetches data.
/// @param force true to force reload.
/// @return the data
/// @throws NetworkException if host is unreachable.
Data load(bool force) { ... }

良い例：

/// Fetches the remote data.
///
/// If [force] is true, this bypasses the local cache and forces a
/// network request.
///
/// Throws a [NetworkException] if the host is unreachable.
Data load(bool force) { ... }

2. 注釈の配置に関する落とし穴

悪い例：

@override
/// Renders the widget to the screen.
Widget build(BuildContext context) { ... }

良い例：

/// Renders the widget to the screen.
@override
Widget build(BuildContext context) { ... }

3. 書き出しと文調

悪い例：

/// Gets if the connection is active.
bool get isActive => _active;

/// This method initializes the connection.
void init() { ... }

良い例：

/// Whether the connection is active.
bool get isActive => _active;

/// Initializes the connection.
void init() { ... }

4. コンストラクターへのリンク

悪い例：

/// Creates a new user. Similar to calling [User()].
User.create() { ... }

良い例：

/// Creates a new user. Similar to calling [User.new].
User.create() { ... }

5. スコープ外のリンク（@docImport）

悪い例：

import 'package:http/http.dart'; // Adds unnecessary runtime dependency just for docs

/// To use this, you must pass a [Client].

良い例：

/// @docImport 'package:http/http.dart';
library;

/// To use this, you must pass a [Client].