doc_examples 设计

设计目标

为库的主要工作流保留一小组始终参与编译的示例，使破坏已文档化工作流的 API 变更会立即导致文档门禁（just docs）失败。

数学背景

无；这些示例重述的是它们所用包的 API 页面和设计页面中规定的行为。

设计决策

• 文学式测试包。 MoonBit 会将包的 README.mbt.md 中的 moonbit check 代码块作为测试编译，因此这些示例既是可读的 Markdown，又是真正的测试，无需单独的测试文件。
• 示例少，覆盖的包多。 每个代码块端到端地演练一个工作流；穷尽的行为测试属于各个包自身的测试以及 consistency。
• 警告即错误。 门禁以 --deny-warn 运行，因此示例中永远不会出现已弃用的 API。

正确性 / 不变式

• 每个代码块都是一个名称唯一的测试，并在 native 目标上通过。
• 该包没有运行时代码，也没有公共项。

被否决的替代方案

• 示例只放在手册页面中。 在模块内保留一个包，可使最小示例集通过普通测试命令保持可编译，而不依赖任何文档工具。

边界

• 不是 API；任何代码都不得导入它。
• 不提供性能或符合性证据。