Luna Flow
日本語

リポジトリの規約

これらの規則は floating に対して Luna-Flow のドキュメント標準に追加されるものであり、標準を緩めることはありません。マニュアルは現在のブランチの実装を説明します。現在のリリースは 0.8.0 で、これは moon.mod のバージョンです。

章とガイド

各パッケージは章ごとに 1 ページを持ち、ページ名はパッケージパスに従います。

  1. API リファレンス（api/<package>.md） は、すべての公開型、関数、メソッド、エラー、値を、そのシグネチャと観測可能な意味論とともに列挙します。
  2. チュートリアル（tutorial/<package>.md） は、コンパイル可能な小さな例を使ってタスクを順に解説します。
  3. 設計（design/<package>.md） は、表現、数学、不変条件、下された判断を説明し、最後にパッケージの境界を述べます。

四つの数値コア bin_float、decimal、decimal_gda、ball_float には、標準が許す範囲でさらに二つの章があります。

  1. 適合性（conformance/<package>.md） は、固定された有限の証拠に基づく主張とその除外事項を述べます。
  2. 性能（performance/<package>.md） は、API としての約束をすることなく、再現可能な計測とターゲット固有のディスパッチの証拠を記録します。

ガイドは tools/doc_quality.py によって固定されています。index.md（概要とパッケージマップ）、getting_started.md（パッケージの選択と最初のステップ）、numeric_semantics.md（共通の数値用語）、architecture.md（レイヤーと責務）、verification.md（ゲートと適合性の範囲）、performance_audit.md（過去の性能ベースラインの監査）、そしてこのページです。そのリストを更新せずにガイドを追加したり名前を変更したりしないでください。

README.md は現在のリリースの位置付けを示し、マニュアルへの入口となります。CHANGELOG.md はリリース履歴と移行に関する注記を扱います。

パッケージページ

  • すべての moon.pkg を反映させます。src/<path>/moon.pkg のパッケージは api/<path>.md、tutorial/<path>.md、design/<path>.md で説明します。ファイルはパッケージを作らず、moon.pkg の境界がパッケージを作ります。
  • すべてのパッケージに三つのページすべてを用意します。アプリケーション API を持たないパッケージ（フロントエンド、CLI、internal/*、bench/*、consistency、doc_examples）も、生成されたインターフェース、メンテナー向けのワークフロー、安定性の境界を文書化します。
  • 各パッケージは src/<path>/README.mbt.md も持ちます。
  • pkg.generated.mbti は公開面の一覧であり、振る舞いはソースとテストが定義します。メソッドをドット構文で呼び出せると文書化してよいのは、.mbti がそれを pub fn Type::name として記載している場合だけです。トレイト実装のメソッドは暗黙には昇格されず、pub extend で宣言する必要があります。
  • 計画中の API を既存のものとして文書化しないでください。また、研究メモを独立したページとして残さないでください。永続的な結論は設計・適合性・性能のページに昇格させ、置き換えられた履歴は CHANGELOG.md に移してください。
  • ページで名前を挙げるのは現在のリリースだけです。古いリリースに言及してよいのは、そのバージョンに対する <!-- historical-performance-baseline: X.Y.Z --> マーカーを持つページに限られます。tools/doc_quality.py はそれ以外の過去のバージョンを拒否します。

API スナップショット

すべての API ページは ## Complete public interface で終わり、その本文はマーカー <!-- generated-api-start --> と <!-- generated-api-end --> の間に置かれた、パッケージの pkg.generated.mbti の正確なコピーで、mbti としてフェンスされます。ページ本文中の個々のシグネチャも mbti ブロックです。tools/doc_quality.py はスナップショットを生成ファイルと比較する（古い moonbit フェンスも受け付けます）ので、moon info がインターフェースを変更したときは必ず再生成してください。

数値文書の規則

  • precision、rounding、classify、sign、normalized、quantum、context、flags は数値意味論で定義されたとおりに使用してください。
  • 格納表現、厳密値、丸められた結果、ステータスフラグ、checked エラー、区間の包含区間を区別してください。
  • パースが量子を保持する場合と、正規化が値を変えずにコホートを変える場合を明記してください。
  • API が用いる順序を明示してください。compare、<、ソートは、すべての NaN をすべての数より上に置く全前順序です。IEEE の半順序（unordered を含む）と totalOrder は別の API です。区間値にスカラーの順序があるかのように示唆してはなりません。
  • *_ctx API では、返される値とフラグの両方を文書化してください。
  • checked API とラッパーでは、ドメイン固有の遷移、すなわち結果のエラー、IEEE フラグの蓄積、あるいは GDA トラップによる短絡とその回復を文書化してください。
  • decimal と decimal_gda は別 contract として説明します。IEEE operation は per-operation flags を返し、GDA operation は GdaOutcome で sticky status と trap を thread します。
  • 数式は TeX（$…$、$$…$$）で書き、導出が依拠する標準の条項や古典的な結果を引用してください。

例

  • 実行可能な例は完全なトップレベル項目（通常は test ブロック）で、moonbit としてフェンスし、出力を inspect で示します。これらは現在のブランチに対してコンパイルされ、パスしなければなりません。
  • 部分的なスニペット、本文中のシグネチャ、実行可能パッケージのコード、モジュール外からインポートできない internal/* のコードは moonbit nocheck としてフェンスし、moon.pkg のスニペットは text としてフェンスします。
  • インポートのエイリアス: Luna-Flow/luna-generic は @lf_alg、Luna-Flow/arithmetic は @lf_arith とします。floating のパッケージはデフォルトのエイリアス（@bin_float、@decimal、…）を使用します。
  • .mbti に記載されているものだけを呼び出してください。たとえば BinFloat には to_double や is_finite メソッドはありません。to_shortest_string と @def.is_finite(x) を使用してください。

翻訳

doc/manual の英語ページが唯一のソースです。翻訳は doc/conf.json に列挙されたロケールの gettext カタログ doc/locale/<locale>/LC_MESSAGES/manual.po に置かれ、ページのコピーとして編集されることはありません。識別子、パッケージ名、パス、コマンド、バージョン文字列、数式は翻訳しないでください。Typst の添付ファイルは doc/attachments/ に置かれ、すべてのロケールで共有されます。

レビューチェック

  1. moon info を実行し、変更された各 pkg.generated.mbti を対応する API ページと比較して、## Complete public interface のスナップショットを更新します。
  2. すべての moon.pkg に api/、tutorial/、design/ のページ（および四つのコアについては証拠ページ）がそろっていることを確認します。
  3. 変更されたすべての例（moonbit ブロック）を現在のブランチに対してコンパイルし、実行します。
  4. python3 tools/doc_quality.py（または src/doc_examples のテストも実行する just docs）を実行します。
  5. lunadoc update を実行して doc/locale/manual.pot を更新してカタログをマージし、新規エントリと fuzzy エントリを翻訳してから、lunadoc status（ロケールごとのカバレッジ）と lunadoc check --compile（レイアウト、カタログ、リンク、Typst の添付ファイル）を確認します。
  6. 提出前に moon fmt、moon check --target all --deny-warn、関連するテスト、just pr を実行します。
  7. リリースのバージョンを上げるときは、moon.mod、README.md 内のバージョン、このページ、CHANGELOG.md を同時に更新します。