ドキュメント標準

このリポジトリのドキュメントは、現在のブランチ実装を基準に記述します。2026-06-14 時点の文書基準は 0.3.0 です。

ドキュメントの種類と構成

主なドキュメントの種類

1. APIリファレンス (api.md) - 各公開インターフェースの詳細な仕様記述
2. ユーザガイド (tutorial.md) - 利用者向けのチュートリアルとベストプラクティス
3. 設計ドキュメント (design.md) - 開発者向けのアーキテクチャとアルゴリズムの説明
4. 性能レポート - 将来再構築する性能・計測ドキュメントのための予約枠

ドキュメント構成の原則

• パッケージ/ファイルごとに構成します。例：

  doc/
    |- en_US
    |- ja_JP 
    |- zh_CN
        |- immut
        |   |- matrix
        |   |   |- api.md
        |   |   |- tutorial.md
        |   |   |- design.md
        |   |- ...
        |- mutable
        |   |- matrix
        |   |   |- ...
        |   |- ...
        |- ...

• 各パッケージの下で、vector、matrix などのファイルごとにさらに細分化します。

• ドキュメントとコード構造の一貫性を維持します。

• リポジトリ実装に存在しない未公開 API を先回りして記述してはいけません。

mutable と immutable の共通規約

API 整合性の原則

• mutable と immutable は、可能な限り同じ公開 API を提供します。
• 両方のパッケージが同じ機能を持つ場合は、関数名、引数順、戻り値の意味、エラー規約を揃えることを優先します。
• 完全に揃えられない場合は、差分、理由、推奨される利用場面を文書で明示します。
• 新しい公開 API を追加するときは、原則として両方のパッケージで提供すべきかを検討します。

immutable パッケージの設計原則

• 関数型、宣言的、かつ合成しやすいインターフェース設計を優先します。
• 破壊的更新を露出するよりも、新しい値を返す形を優先します。
• 呼び出し側に隠れた状態、共有可変状態、タイミング依存の振る舞いを意識させないようにします。
• ドキュメントでは値セマンティクス、参照透過性、合成方法を重視して説明します。
• 性能上のトレードオフがある場合でも、まず外部セマンティクスの明確さと安定性を守ります。

mutable パッケージの設計原則

• 性能、メモリ再利用、低レベル実行効率を優先します。
• ライブラリ内部での可変状態、破壊的更新、その他の副作用は許容されます。
• ただし、それらの副作用は実装内部に閉じ込め、利用者のメンタルモデルへ漏らさないようにします。
• 公開 API は依然として純粋で安定しており、関数型の使い心地を保つべきです。内部の可変実装を契約として露出してはいけません。
• immutable と異なる専用 API は、性能上の利点が明確かつ必要な場合にのみ導入します。

ドキュメント記述要件

• mutable と immutable の API 文書では、可能な限り同じ節構成と用語を使います。
• 対応する API 同士を相互参照できるようにし、意味論とコストモデルを比較しやすくします。
• 外部セマンティクスと内部実装方針を明確に分けて記述します。
• キャッシュ、再利用、破壊的計算などの性能最適化の話題は、API の意味論ではなく設計文書や将来の性能レポートに書きます。
• mutable 側で性能重視の設計により可観測な挙動差がある場合は、内部実装の説明だけで済ませず、その挙動を明示します。