Luna Flow

日本語

English
简体中文

日本語

English
简体中文

Appearance

ドキュメント標準 ​

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

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

主なドキュメントの種類 ​

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

README.md は現行基準の文書であり、現在のリリース基準、入口、パッケージの位置づけ、 読者向け案内をまとめます。CHANGELOG.md は過去バージョンの時系列と、 古いリリースノートを担当します。

ドキュメント構成の原則 ​

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

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

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

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

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

  • en_US、zh_CN、ja_JP の 3 言語で同じ Markdown ファイル集合を保ちます。

  • 各言語で見出しの大枠と節順を揃えます。コード上の理由がない限り、言語ごとに独自構成へ崩しません。

  • 既定では英語ドキュメントを構成上の基準とし、同じ内容を中国語と日本語へ自然にローカライズします。

  • doc/* を唯一の手書き本文の事実源とします。src/doc_* パッケージは文書公開層であり、 独立した Markdown 本文ではなく、これらのファイルへの symlink を置きます。

  • README.md は現在基準に集中させ、古いバージョン要約は CHANGELOG.md へ移します。

mutable と immutable の共通規約 ​

API 整合性の原則 ​

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

immutable パッケージの設計原則 ​

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

mutable パッケージの設計原則 ​

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

ドキュメント記述要件 ​

  • mutable と immutable の API 文書では、可能な限り同じ節構成と用語を使います。
  • 対応する API 同士を相互参照できるようにし、意味論とコストモデルを比較しやすくします。
  • 外部セマンティクスと内部実装方針を明確に分けて記述します。
  • キャッシュ、再利用、破壊的計算などの性能最適化の話題は、API の意味論ではなく設計文書や将来の性能レポートに書きます。
  • mutable 側で性能重視の設計により可観測な挙動差がある場合は、内部実装の説明だけで済ませず、その挙動を明示します。
  • コード識別子、API 名、型名、パッケージ名、ファイルパス、バージョン文字列は翻訳しません。
  • API 文書は仕様中心、tutorial は使い方中心、design は責務・境界・トレードオフ中心に書き分けます。
  • バックエンドラッパーパッケージでは、プラットフォーム制約、変換境界、各挙動がローカル実装か外部ライブラリのカーネル委譲かを明記します。
  • 冗長な言い回しやリリースノート調の文章を避け、短く直接的な技術文に寄せます。
  • 中国語文書は自然な書面技術中国語、日本語文書は自然な技術文体にします。逐語訳や他言語の文型の持ち込みは避けます。