用途:面向 @data-client 公共库接口的文档编写规范,用于创建和维护 API 参考、README、JSDoc/TSDoc 注释及用法示例。
文档结构:/docs 按包组织,docs/core/ 对应 @data-client/core 与 @data-client/react,docs/rest/ 对应 @data-client/rest,docs/graphql/ 对应 @data-client/graphql。每包下含 api/(每个公开类/函数/hook 一个文件)、guides/、concepts/、getting-started/ 子目录。
命名:API 文档文件名与导出名一致,如 useSuspense.ts 对应 docs/core/api/useSuspense.md,RestEndpoint.js 对应 docs/rest/api/RestEndpoint.md。
格式:每个 API 文档应包含 frontmatter(title、sidebar_label)、功能描述、用法示例、参数/选项与返回类型、TypeScript 类型、相关 API 链接。
定位文件:确认代码所属包,检查包 index.ts 或主入口的导出,按名称匹配 docs/{package}/api/ 下文件;若涉及工作流变化还需查看对应 guides/。
示例:新增 hook 时创建对应 API 文档并附示例;修改方法签名时更新文档、补充迁移说明与示例;弃用 API 时加弃用提示、记录替代 API 并按需加迁移指南;新增选项时在文档中说明并配示例。
限制与注意:公共 API 指包主入口导出的内容;内部/私有 API(以 _ 前缀、未导出或标记 @internal)无需更新文档。文档应与代码改动在同一提交或 PR 中更新。资料未提供具体构建验证命令等细节。