ドキュメント標準

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

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

主なドキュメントの種類

1. API リファレンス（api.md）：公開インターフェースと可観測な挙動の仕様
2. チュートリアル（tutorial.md）：利用例と選択指針
3. 設計ドキュメント（design.md）：能力境界、責務、実装上のトレードオフ

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

構成原則

• 実際のパッケージ境界または capability 境界に沿って文書を配置します。
• api.md、tutorial.md、design.md の役割を分けます。
• 現在のブランチに存在する API と挙動だけを記述します。
• en_US、zh_CN、ja_JP で同じ Markdown ファイル集合を維持します。
• コード上の事実が別構成を要求しない限り、各言語の見出し順を揃えます。
• 英語文書を構成上の基準とし、同じ事実を中国語と日本語へ自然にローカライズします。
• README.md は現行基準に集中させ、古い要約は CHANGELOG.md へ移します。

記述要件

• 識別子、型名、trait 名、パッケージ名、パス、コマンド、バージョン文字列は翻訳しません。
• API の保証、実装戦略、既知の制約を明確に分けます。
• capability がインターフェース境界にとどまり、組み込みインスタンスがすべての意味論を 実装していない場合は、その点を明記します。
• 宣伝的な文体を避け、短く直接的な技術文を使います。
• MoonBit の例では、Luna-Flow/luna-generic に @lf_alg、 Luna-Flow/arithmetic に @lf_arith を使います。
• 中国語と日本語は逐語訳ではなく、それぞれ自然な技術文体で記述します。