文档标准

本仓库文档应以当前分支中的真实实现为准。截至 2026-07-11，当前文档基线为 0.4.7。

文档类型与组织

主要文档类型

1. API参考文档(api.md) - 详细描述每个公开接口的规格说明
2. 用户指南(tutorial.md) - 面向使用者的教程和最佳实践
3. 设计文档(design.md) - 面向开发者的架构和算法说明
4. 性能报告 - 预留给未来重建的性能与测量文档

README.md 是当前基线文档，负责说明当前版本基线、阅读入口、包定位和读者路径。 CHANGELOG.md 负责承载历史版本时间线和较旧的发布说明。

文档组织原则

• 按照包/文件来组织，例如

  doc/
    |- en_US
    |- ja_JP
    |- zh_CN
        |- immut
        |   |- matrix
        |   |   |- api.md
        |   |   |- tutorial.md
        |   |   |- design.md
        |   |- ...
        |- mutable
        |   |- matrix
        |   |   |- ...
        |   |- ...
        |- ...

• 每个包下再按 vector、matrix 等主题文件细分

• 保持文档与代码结构的一致性

• 不要记录仓库实现里还不存在的“计划中 API”

• en_US、zh_CN、ja_JP 三套文档应保持相同的 Markdown 文件集合

• 各语言文档的一级、二级小节顺序应尽量保持一致；除非代码事实要求，否则不要单独改写结构

• 默认以英文文档作为结构基准，再把同一份信息自然地本地化为中文和日文

• doc/* 是唯一手写正文事实源。src/doc_* 包只是文档暴露层，应通过软链接指回 这些文件，不应保留独立的 Markdown 正文

• README.md 应聚焦当前基线；较旧的版本摘要应移动到 CHANGELOG.md

mutable 与 immutable 的统一规范

API 对齐原则

• mutable 与 immutable 应尽可能提供相同的公开 API
• 当两个包都支持同一能力时，优先保持一致的函数名、参数顺序、返回语义与错误约定
• 如果因为实现约束无法完全一致，文档必须明确说明差异、原因以及推荐使用场景
• 新增公开接口时，默认同时评估是否应在两个包中都提供

immutable 包的设计原则

• 优先采用函数式、声明式、可组合的接口设计
• 优先返回新值，而不是暴露原地修改语义
• 避免让调用者感知隐藏状态、共享可变状态或时序敏感行为
• 文档应强调值语义、引用透明性与组合方式
• 如果存在性能上的妥协，仍应优先保持外部语义清晰、稳定、易推理

mutable 包的设计原则

• 优先关注性能、内存复用与底层执行效率
• 允许在库内部使用可变状态、原地更新和其他必要副作用
• 这些副作用应尽可能封装在实现内部，不应扩散到调用者的心智模型中
• 对外 API 仍应保持纯净、稳定、函数式风格，避免把内部可变实现直接暴露为接口约束
• 只有在性能收益明确且必要时，才引入与 immutable 不一致的特殊接口

文档写作要求

• 在 mutable 与 immutable 的 API 文档中，优先使用相同的小节结构与术语
• 对应接口应互相链接或交叉引用，方便读者比较两个包的语义与成本
• 文档需要明确区分“外部语义”与“内部实现策略”
• 性能优化、缓存、复用、原地计算等内容应写入设计文档或未来的性能报告，而不是污染 API 语义定义
• 当某个 mutable 接口为了性能采取特殊行为时，必须明确写出其可观察影响，而不是只描述内部实现细节
• 不要翻译代码标识符、API 名、类型名、包名、文件路径和版本号
• API 文档偏规格说明，tutorial 偏使用路径，design 偏职责边界与取舍，不要把三类文体混写
• 后端包装包需要说明平台约束、转换边界，以及相关行为是在本地实现还是委托给外部库内核
• 尽量使用短句、直述句，避免口语化、宣传式或版本说明式表达
• 中文文档应当是自然的书面技术汉语，避免逐词硬翻和不必要的中英夹杂
• 日文文档应当是自然的技术文体，不应照搬中文或英文句式