用途:把 API、配置项、CLI、schema、错误码等公开接口整理成可搜索、结构统一的权威参考文档,而非教程式叙述。
主要能力:按五阶段流程组织——清点接口、参数与约束;按统一条目格式撰写(签名、Since 版本、Deprecated 标记、参数表、返回值、抛错、示例、See Also);对照实现与测试核验签名、默认值、错误条件和示例;按概览、快速参考、认证、详细参考、错误参考、术语表、变更日志分层组织并添加目录、索引、版本徽章;通过版本标记、弃用迁移指引和变更日志维护。
使用方式:资料给出引用文件 references/documentation-patterns.md,用于 API 文档结构、术语表模式、交叉引用、版本化文档、参数表与配置指南;未提供安装命令或具体调用命令。写作规则包括:描述行为而非实现;每个参数占一行;每个条目至少一个可用示例;明确取值范围、长度与格式约束;交叉引用相关方法、配置与错误码。参数统一用表格,禁止内联列表;配置块示例中保留原样,如 port: 3000、timeout: 30000、max_body_size: "1mb"。
适用场景:REST、GraphQL、gRPC API 参考;含全部参数的配置指南;数据库或数据模型 schema 文档;含全部命令与标志的 CLI 参考;完整技术规范;错误码、状态码与异常目录;版本升级迁移指南。
限制与注意事项:事实来源优先级为实现代码、测试、类型定义/ schema、既有文档(可能过期需核验)。反模式包括记录会随时变动的内部/私有接口、用“显而易见”代替真实描述、因类型可读而省略错误说明、复制未验证的示例、在参考条目中混入教程叙述、文档落后实现超过一个版本。平台、收费、价格等信息暂未提供。