doc_examples の設計

設計目標

ライブラリの主要なワークフローについて、常にコンパイルされる小さな例の集合を 1 つ保持します。これにより、文書化されたワークフローを壊す API の変更は、ドキュメントのゲート（just docs）で直ちに失敗します。

数学的背景

ありません。例は、使用するパッケージの API ページと設計ページで規定された振る舞いを再掲するものです。

設計上の判断

• 文芸的テストパッケージ。 MoonBit はパッケージの README.mbt.md 内の moonbit check ブロックをテストとしてコンパイルするため、例は読みやすい Markdown であると同時に実際のテストでもあり、別のテストファイルは不要です。
• 少ない例、多くのパッケージ。 各ブロックは 1 つのワークフローを端から端まで実行します。網羅的な振る舞いは各パッケージのテストと consistency に属します。
• 警告はエラー。 ゲートは --deny-warn 付きで実行されるため、例が非推奨の API を示すことはありません。

正しさ／不変条件

• すべてのブロックは一意の名前を持つテストであり、native ターゲットで成功します。
• このパッケージには実行時コードも公開項目もありません。

却下した代替案

• マニュアルのページ内にだけ例を置く。 モジュール内のパッケージであれば、ドキュメントツールに依存せず、通常のテストコマンドで最小限の集合をコンパイルし続けられます。

境界

• API ではありません。何もこれをインポートしてはなりません。
• 性能や適合性の根拠は提供しません。