Skip to content

DocumentationComments

Jump to bottom
github-actions[bot] edited this page Aug 27, 2026 · 3 revisions

← Home

ドキュメントコメント規約

このドキュメントは、FloatSoda のソースコードに記述する XML ドキュメントコメントの規約をまとめたものです。

FloatSoda のドキュメントコメントは、ソースコードに埋め込まれた正式な API Reference の原稿として扱います。目的は、IDE および自動生成された API Reference 上で、API の役割・契約・副作用を正確に確認できるようにすることです。チュートリアル・設計背景・概念解説・実践的な使用例などは API Reference の責務に含めず、原則としてドキュメントサイトに記載します。

1. 適用範囲

ドキュメントコメントは、アクセス修飾子にかかわらず、原則としてすべての型およびメンバーに記述します。対象には次の要素を含みます。

  • クラス
  • 構造体
  • レコード
  • インターフェース
  • 列挙型
  • デリゲート
  • コンストラクター
  • メソッド
  • プロパティ
  • フィールド
  • イベント
  • 演算子
  • 型パラメーター
  • 列挙値

public / protected / internal / private のいずれであるかを問わず、その要素の役割や契約が存在する場合はドキュメントコメントを記述します。内部 API および非公開メンバーについても、フレームワークの保守・コードレビュー・デバッグ・将来の API 変更に必要な内部向け API Reference として扱います。

ただし、次のような要素は例外として省略できます。

  • コンパイラーまたはコード生成によって生成される要素
  • 意味や契約を持たない単純なバッキングフィールド
  • 自明な定数の内部保持のみを目的とするフィールド
  • ドキュメントコメントを継承し、追加または変更された契約がないオーバーライド
  • 一時的なローカル実装に限定され、独立した役割を持たない要素

省略できるか判断に迷う場合は、ドキュメントコメントを記述します。

2. 基本方針

ドキュメントコメントには、API Reference として必要な情報を記載します。

  • <summary> には、その API が何を行うかを簡潔に記述する。
  • メソッドおよびコンストラクターの引数は、<param> を使用して省略せず説明する。
  • 型パラメーターがある場合は、<typeparam> を使用して役割や制約を説明する。
  • 戻り値がある場合は、<returns> を使用して戻り値の意味を説明する。
  • プロパティの値に補足が必要な場合は、<value> を使用して意味や制約を説明する。
  • 例外を送出する場合は、<exception> を使用して発生条件を記述する。
  • 単位・値の範囲・null の可否・既定値・失敗時の挙動など、API を正しく使用するために必要な契約を明記する。
  • 状態変更・Dirty フラグの変更・再計算・再描画など、観測可能な副作用を明記する。
  • <remarks> は、要約・引数・戻り値だけでは不足する契約上の補足がある場合に使用する。
  • 長い使用例・チュートリアル・設計意図・内部構造の解説はドキュメントサイトに記載する。
  • <example> は原則として使用しない。API Reference 上で確認する必要性が高い短い例に限り使用できる。

3. API Reference とドキュメントサイトの責務

ドキュメントコメント(API Reference)には、次の内容を記載します。

  • API の役割
  • 引数および型パラメーターの意味
  • 戻り値の意味
  • プロパティ値の意味
  • 発生する例外と条件
  • 値の単位や有効範囲
  • null の可否
  • 既定値
  • 副作用
  • Dirty フラグの変更
  • 変更が伝播する範囲
  • 再実行される処理
  • 失敗時の挙動
  • 密接に関連する API

ドキュメントサイトには、次の内容を記載します。

  • チュートリアル
  • API の具体的な使い方
  • 複数 API を組み合わせた例
  • Widget・Element・RenderObject の概念解説
  • Flutter との対応関係
  • 設計意図
  • 内部構造
  • よくある間違い
  • 実践的なサンプル
  • パイプライン全体の解説

原則として、ドキュメントコメントは「何であるか」「どのような契約か」「どのような副作用があるか」を説明し、ドキュメントサイトは「どのように使うか」を説明します。

4. 引数、戻り値および型パラメーター

すべての引数に <param> を記述します。引数名や型を単に言い換えるだけの説明は避け、意味・単位・有効範囲・null の可否・所有権・ライフタイム・副作用などを記載します。

/// <param name="width">
/// オーバーレイの幅。単位はメートルで、0より大きい値を指定します。
/// </param>

型パラメーターには、その型が担う役割と必要な制約を記載します。

/// <typeparam name="TWidget">
/// このElementが管理するWidgetの型。
/// </typeparam>

戻り値がある場合は、<returns> に成功時・失敗時・対象が存在しない場合など、それぞれの値が表す意味を記載します。

/// <returns>
/// イベントが処理された場合は <see langword="true"/>。
/// 処理対象が存在しない場合は <see langword="false"/>。
/// </returns>

5. Dirty フラグの変更

型またはメンバーが Dirty フラグを変更する場合は、変更される Dirty フラグをドキュメントコメント内で明示します。Dirty フラグの変更は、レイアウト・描画・合成などの後続処理に影響するため、API Reference 上の副作用として扱います。

必要に応じて、次の情報を記載します。

  • 直接変更される Dirty フラグ
  • 間接的に変更される Dirty フラグ
  • 変更が伝播する関連オブジェクト
  • 伝播が停止する境界
  • 再実行されるパイプライン処理
  • 値が変化しなかった場合の挙動

特に次の Dirty 状態を変更する場合は明示します。

  • Layout Dirty
  • Paint Dirty
  • Compositing Dirty
  • Widget または Element の再構築を要求する状態
  • FloatSoda 固有のパイプライン Dirty 状態
/// <summary>
/// 子要素に適用する内側の余白を取得または設定します。
/// </summary>
/// <value>
/// 子要素の周囲に適用する余白。
/// </value>
/// <remarks>
/// 値が変更された場合、このRenderObjectをLayout Dirtyとしてマークします。
/// これにより、次のパイプライン更新時にサイズと位置が再計算されます。
/// 値が変更されなかった場合、Dirty状態は変更されません。
/// </remarks>
public EdgeInsets Padding
{
    get => _padding;
    set
    {
        if (_padding == value)
        {
            return;
        }

        _padding = value;
        MarkNeedsLayout();
    }
}

実装メソッド名だけを記載するのではなく、その結果として何が起きるかを説明します。

// 不十分
/// <remarks>
/// <c>MarkNeedsLayout()</c>を呼び出します。
/// </remarks>
// 推奨
/// <remarks>
/// このRenderObjectをLayout Dirtyとしてマークし、
/// 次のパイプライン更新時にサイズと位置を再計算します。
/// </remarks>

継承元の実装によって Dirty フラグが変更され、その挙動を派生型が変更または追加しない場合は、同じ説明を派生型へ重複して記載しません。派生型が Dirty フラグの種類・伝播範囲・または再実行される処理を変更する場合は、その差分を明示します。

6. 関連型への参照

Widget・Element・RenderObject の間に対応関係がある場合は、API Reference から相互に参照できるようにします。参照対象には、次のような意味上の関係を含みます。

  • 対応する Widget
  • 対応する Element
  • 対応する RenderObject
  • 密接に関連する API
  • 代替となる API
  • 対になる API

参照には、必要に応じて <see> または <seealso> を使用します。

/// <summary>
/// 子要素を利用可能な領域の中央に配置します。
/// </summary>
/// <remarks>
/// <see cref="RenderCenter"/>の構成を宣言します。
/// </remarks>
/// <seealso cref="RenderCenter"/>
public sealed record Center : SingleChildRenderObjectWidget;

専用の Element 型が存在する場合は、対応する Widget と RenderObject を参照します。共通 Element を使用しており、型固有の Element が存在しない場合は、対応関係を説明するためだけに専用 Element を作成しません。

7. 参照しないもの

次の要素には、原則として明示的なリンクを追加しません。

  • 継承元の型
  • 実装しているインターフェース
  • 型階層から自動的に判別できる型
  • 同じ名前空間に属するだけの型
  • 関係が薄い型

継承関係やインターフェースの実装関係は、IDE および API Reference 生成ツールに委ねます。ドキュメントコメントでは、型階層だけでは表現できない意味上の関係を補足します。

8. 継承およびオーバーライド

基底メンバーと契約が完全に同一であり、追加の説明がない場合は、<inheritdoc/> を使用できます。

/// <inheritdoc/>
public override void PerformLayout()
{
    // ...
}

ただし、次のいずれかに該当する場合は、<inheritdoc/> だけで済ませず、変更された契約を明示します。

  • 振る舞いを追加または変更する
  • 例外条件を追加する
  • Dirty フラグの種類を変更する
  • Dirty 状態の伝播範囲を変更する
  • 副作用を追加する
  • 戻り値や null の扱いを変更する
  • スレッド・所有権・ライフタイムに関する制約を追加する

9. 記述言語

XML ドキュメントコメント(/// <summary>)は日本語のみで書きます。1つのソースに2言語を併記することはしません。これは FloatSoda が日本語をニュートラル(既定)言語とする方針の一部です。

英語版はビルドパイプラインでの機械翻訳(LLM)によるサテライト XML 生成を将来検討していますが、未実装です。それまでソースは日本語一本で書き進めて問題ありません。サテライト XML の配置と仕組みの詳細は Localization を参照してください。

10. 入力語彙

ドキュメントコメントの説明文では、入力デバイスの語彙として「マウス」単独ではなく「ポインター(レーザーポインター/マウス)」のように書きます。これは FloatSoda が型・メンバー名を含めて入力語彙を「ポインター (Pointer)」で統一する方針の一部です。詳細と例外(外部 API の固有名詞をそのまま写す薄いラッパー)は APIDesign の「入力語彙は『ポインター (Pointer)』で統一する」を参照してください。

11. 原則

FloatSoda のドキュメントコメントは、補助的な実装コメントではなく、正式な API Reference を構成する情報です。

  • ドキュメントコメントは、公開 API だけでなく、原則としてすべての型およびメンバーに記述する。
  • API の役割・引数・型パラメーター・戻り値・例外・制約・副作用・および Dirty 状態の変更は、ドキュメントコメント内で完結させる。
  • 長い説明・学習用途の内容・設計背景・実践的な使用例は含めず、ドキュメントサイトへ分離する。
  • 型階層はツールに任せ、意味上の関係と観測可能な副作用をコメントで補足する。

原則として、ドキュメントコメントは「何であるか」「どのような契約か」「どのような副作用があるか」を説明し、ドキュメントサイトは利用者に「どのように使うか」を教えます。

関連ページ

  • APIDesign — API 設計規約(命名・イミュータビリティ・入力語彙)
  • Localization — 記述言語とサテライト XML の仕組み
  • RenderObjects — Dirty フラグと差分レイアウト・描画の実際
  • Home — ドキュメント一覧

Pages

Clone this wiki locally