========================================================================
コードコメント・ドキュメント規則 (Code Comment & Documentation Guide)
========================================================================


1. 基本方針 (Basic Policy)
------------------------------------------------------------------------
コードの可読性と保守性を高めるため，ファイル・型・関数・定数それぞれに対して
適切な粒度でコメントを記述する．

・言語: 日本語で記述する．
・句読点: 「，」（全角カンマ）を使用し，文末の句点（「．」「。」）は付けない
    - 列挙が続く場合は「，」で区切る
・文体: 体言止め，または「〜する」形で統一する


2. コメントの種類と用途 (Comment Types)
------------------------------------------------------------------------

2-1. ファイルドキュメント (File Header Doc Comment)
    ・ファイルの先頭に必ず記述する．
    ・JSDoc形式（`/** */`）を使用する．
    ・書式:

        /**
         * [ファイル名（拡張子なし）]
         * [ファイルの主な責務を1行で説明]
         * [補足情報があれば続けて記述]
         */

    ・例:

        /**
         * useJoystick
         * ジョイスティック入力を受け取り，座標計算と正規化ベクトルの出力を行うフック
         * UI描画に必要な中心点・ノブ位置・半径も合わせて提供する
         */

2-2. 型・定数ドキュメント (Type & Constant Doc Comment)
    ・`export` される型（`type`，`interface`）および定数（`const`）には必ず記述する．
    ・JSDoc形式の1行コメント（`/** */`）を直前行に記述する．
    ・書式:

        /** [その型・定数が何を表すかを端的に説明] */
        export type / const ...

    ・例:

        /** UI側と共有する最大半径の既定値 */
        export const MAX_DIST = 60;

        /** 2D座標の簡易型 */
        type Point = { x: number; y: number };

        /** フックが返すUI向けの状態とハンドラ */
        type UseJoystickReturn = { ... };

2-3. 関数・コンポーネント・フックドキュメント (Function Doc Comment)
    ・`export` される関数，Reactコンポーネント，フックには必ず記述する．
    ・JSDoc形式の1行コメント（`/** */`）を直前行に記述する．
    ・書式:

        /** [その関数・コンポーネントが何をするかを端的に説明] */
        export const / function ...

    ・例:

        /** 正規化ベクトルの出力とUI用の座標を提供するフック */
        export const useJoystick = ...

        /** ポインター入力と描画を結びつけるジョイスティックUI */
        export const Joystick = ...

2-4. ブロックコメント (Block Comment)
    ・関数・コンポーネント内で，処理のまとまりが変わる箇所に記述する．
    ・通常の行コメント（`//`）を使用する．
    ・書式:

        // [このブロックの処理を端的に説明]
        ...処理...

    ・例:

        // 入力開始時の基準座標をセットする
        const handleStart = ...

        // 入力座標からベクトルを計算し，半径でクランプして正規化出力する
        const handleMove = ...

2-5. JSXコメント (JSX Comment)
    ・JSX内のブロック区切りには `{/* */}` 形式を使用する．
    ・例:

        {/* 見た目のみの描画（入力は扱わない） */}
        <JoystickView ... />

2-6. 再エクスポートコメント (Re-export Comment)
    ・外部へ再公開する `export { ... }` には1行ドキュメントを付ける．
    ・例:

        /** 入力半径の既定値を外部から参照できるように再公開 */
        export { MAX_DIST } from "./useJoystick";


3. 記述しない場合の判断基準 (When to Omit)
------------------------------------------------------------------------
・ファイル内部でのみ使用し，外部に公開されない型・関数・定数は省略してもよい
・コード自体が自明な場合（変数名で意図が十分伝わる場合）は省略してもよい
・ユニットテストファイルは，テストケース名で意図が伝わる場合は省略してもよい


4. NG例 (Anti-patterns)
------------------------------------------------------------------------
・句点を付ける
    - NG: /** ジョイスティックの入力を受け取る． */
    - OK: /** ジョイスティックの入力を受け取る */

・「、」「。」を使う
    - NG: // 入力開始時の基準座標をセットする。
    - OK: // 入力開始時の基準座標をセットする

・ファイルヘッダーを通常の行コメントで書く
    - NG: // useJoystick: ジョイスティック入力を受け取るフック
    - OK: /** \n * useJoystick\n * ジョイスティック入力を受け取るフック\n */