文档标准

本仓库的文档应描述当前分支中的真实实现。截至 2026-06-14，当前文档基线为 0.3.0。

文档类型与组织

主要文档类型

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

文档组织原则

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

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

• 每个包下按vector、matrix等文件进一步细分

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

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

mutable 与 immutable 的统一规范

API 对齐原则

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

immutable 包的设计原则

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

mutable 包的设计原则

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

文档写作要求

• 在 mutable 与 immutable 的 API 文档中，优先使用相同的小节结构与术语
• 对应接口应互相链接或交叉引用，方便读者比较两个包的语义与成本
• 文档需要明确区分“外部语义”与“内部实现策略”
• 性能优化、缓存、复用、原地计算等内容应写入设计文档或未来的性能报告，而不是污染 API 语义定义
• 当某个 mutable 接口为了性能采取特殊行为时，必须明确写出其可观察影响，而不是只描述内部实现细节