Luna Flow
简体中文

仓库约定

这些规则是 floating 在 Luna-Flow 文档标准之上的补充，绝不会放宽该标准。本手册描述当前分支上的实现。当前发布版本为 0.8.0，即 moon.mod 中的版本。

章节与指南

每个包在每个章节中各有一页，以其包路径命名：

  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 时，才能将其记录为可用点语法调用；trait 实现中的方法不会被隐式提升，必须用 pub extend 声明。
  • 不要把计划中的 API 写成已存在，也不要把研究笔记保留为独立页面。将持久的结论提升到设计、符合性或性能页面中，并把已被取代的历史移入 CHANGELOG.md。
  • 页面只提及当前发布版本。只有当页面带有针对该版本的 <!-- historical-performance-baseline: X.Y.Z --> 标记时，才可以提及更早的版本；tools/doc_quality.py 会拒绝其他任何历史版本。

API 快照

每个 API 页面都以 ## Complete public interface 结尾，其正文是该包 pkg.generated.mbti 的精确副本，位于 <!-- generated-api-start --> 与 <!-- generated-api-end --> 标记之间，并用 mbti 代码块围起。页面正文中的单个签名也使用 mbti 代码块。tools/doc_quality.py 会将快照与生成的文件进行比较（也接受旧的 moonbit 代码块），因此每当 moon info 改变接口时都要重新生成快照。

数值文档规则

  • 按照数值语义中的定义使用 precision、rounding、classify、sign、normalized、quantum、context 和 flags。
  • 区分存储表示、精确值、舍入结果、状态标志、checked 错误和区间包络。
  • 说明解析何时保留量子（quantum），以及规范化何时在不改变值的情况下改变同值类（cohort）。
  • 指明 API 所使用的序。compare、< 和排序是一个全预序，它把每个 NaN 排在所有数之上；IEEE 偏序（含 unordered）和 totalOrder 是单独的 API。切勿暗示区间值存在标量序。
  • 对于 *_ctx API，同时说明返回值和标志。
  • 对于 checked API 和包装器，说明其特定于数值域的状态转换：结果错误、IEEE 标志累积，或 GDA 陷阱短路及其恢复。
  • 必须把 decimal 与 decimal_gda 写成两个独立合同：IEEE 运算返回逐 operation flags，GDA 运算通过 GdaOutcome 传递 sticky status 与 traps。
  • 用 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 中的英文页面是唯一的源文本。译文存放在 gettext 目录 doc/locale/<locale>/LC_MESSAGES/manual.po 中，覆盖 doc/conf.json 所列的语言区域，绝不以页面副本的形式编辑。不要翻译标识符、包名、路径、命令、版本字符串或数学内容。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（或 just docs，它还会运行 src/doc_examples 的测试）。
  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。