Documentation Standard

Repository documentation describes the implementation on the current branch. As of 2026-07-16, the release baseline is 0.7.1.

Document Types And Ownership

1. API reference (api.md) specifies public types, functions, methods, errors, and observable semantics.
2. Tutorial (tutorial.md) provides small executable workflows and usage guidance.
3. Design (design.md) explains representation, invariants, responsibility boundaries, and implementation tradeoffs.
4. Conformance (conformance.md) defines a pinned finite evidence claim and its exclusions for each numerical core.
5. Performance (performance.md) records reproducible measurements and target-specific dispatch evidence without making API promises.
6. README provides current-baseline positioning, package entry points, and a reader path.
7. CHANGELOG owns historical release notes and migration history.

The locale root also exposes four cross-package guides: getting_started.md for package selection, numeric_semantics.md for shared numerical vocabulary, architecture.md for responsibility boundaries, and verification.md for conformance scope and reproducible commands.

Structure And Localization

• Mirror every moon.pkg path under the documentation tree. File names do not create MoonBit modules; moon.pkg boundaries do.
• Keep the Markdown file set and top-level section responsibilities aligned across en_US, zh_CN, and ja_JP.
• Do not keep locale-only research pages. Promote durable conclusions into synchronized design, conformance, or performance documents; move superseded history to CHANGELOG.md.
• Treat English as the structural source, then localize naturally. Do not translate identifiers, package names, paths, commands, or version strings.
• Keep README files focused on the current baseline. Move superseded release narratives to CHANGELOG.md.
• Do not document planned APIs as existing. Generated pkg.generated.mbti files are the public-surface inventory; source and tests define behavior.
• Give every package api.md, tutorial.md, and design.md; packages without an application API must still publish their generated inventory, maintainer workflow, and stability boundary.

Numeric Documentation Rules

• Use precision, rounding, classify, sign, normalized, quantum, context, and flags consistently.
• Separate stored representation, exact value, rounded result, status flags, checked errors, and interval enclosure semantics.
• State when parsing preserves quantum and when normalization changes a cohort without changing its mathematical value.
• Never imply total ordering for NaN-containing scalars or interval values.
• For *_ctx APIs, document both the returned value and accumulated flags.
• For *_checked APIs, document the domain-specific state transition: result error, IEEE flag accumulation, or GDA trap short-circuit and recovery.
• Document decimal and decimal_gda as separate contracts: IEEE operations return per-operation flags, while GDA operations thread sticky status and traps through GdaOutcome.
• Keep examples small and checkable. MoonBit import examples must use @lf_alg for Luna-Flow/luna-generic and @lf_arith for Luna-Flow/arithmetic.

Review Checklist

• Compare package docs with pkg.generated.mbti after moon info.
• Verify links and cross-language file alignment.
• Run moon fmt, moon check --target all, relevant tests, and documentation examples or the repository just pr gate as appropriate.
• Update the baseline date/version and changelog during a release bump.