资料贡献指南

概述

asc-comm资料体系包含仓库入口、快速开始、构建测试、API参考、使用指南和样例说明等内容。开发者可以通过提交PR对资料进行纠错、补充和优化。

文档类型	内容	文档目录
仓库入口	项目概述、目录结构、常用文档入口	README.md
快速开始	环境准备、源码下载、构建和UT验证	docs/quick_start.md
构建与依赖	构建脚本、CMake入口、三方依赖说明	docs/zh/guide/
API参考	接口功能、原型、参数、返回值和约束	docs/zh/api/
使用指南	API调用流程、协议能力和注意事项	docs/zh/guide/
样例说明	样例目录入口、运行边界和验证说明	examples/README.md、examples/*/README.md

贡献场景

文档纠错

如果发现资料中存在链接失效、路径错误、命令不可执行、参数值不准确或约束遗漏等问题：

1. 新建 Documentation | 文档反馈 类Issue，说明问题位置和期望修改。
2. 在评论框中输入 /assign 或 /assign @yourself 将该Issue分配给您。
3. 修复后提交PR，并在PR中说明验证方式。

文档补充

如果需要补充接口说明、构建说明、依赖说明、样例说明或常见问题：

1. 新建 Requirement | 需求建议 类Issue，描述补充内容和适用场景。
2. 按照本文档的编写规范补充资料。
3. 同步更新相关入口文档，避免新增内容成为孤立页面。

样例资料补充

新增样例时，需要同步补充样例说明，明确样例用途、前置条件、构建运行方式和验证命令。

编写规范

通用规范

规则	要求
与代码一致	目录结构、构建命令、接口名称、函数原型和返回值应与当前仓库实际内容一致。
适用范围清晰	对需要前置条件或仅适用于特定场景的能力，需要明确说明适用范围和验证方式。
面向验证	快速开始、构建测试和样例文档应说明用户能直接执行什么、不能直接执行什么。
链接有效	新增文档后需要同步更新入口页面，并检查相对链接和图片路径有效。
首次引入加链接	首次提到其他文档负责的概念或API时添加链接，后续重复出现不必反复链接。

文档结构

新增专题文档建议包含以下内容：

1. 背景或适用范围。
2. 前置条件和依赖。
3. 操作步骤或接口使用流程。
4. 约束说明和适用范围。
5. 验证方式。
6. 相关文档链接。

API相关资料

API行为相关资料应与 include/ 下公开头文件保持一致。涉及协议能力、地址约束、对齐要求、调用顺序或产品差异时，需要在API参考和使用指南中同步说明。

样例相关资料

样例资料应说明：

• 样例用途和覆盖的API。
• 样例文件结构。
• 是否可独立构建或运行。
• 构建、运行和验证命令。
• 必要的前置条件和资源准备。

常见修改场景

• 新增接口：同步更新API参考、使用指南、样例说明和文档入口。
• 新增样例：同步更新examples/README.md，说明样例用途、前置条件和验证方式。
• 修改构建流程：同步更新快速开始、构建与测试文档。
• 新增依赖：同步更新三方依赖说明、三方软件清单和Notice。
• 调整目录结构：同步更新README、docs入口和相关相对链接。

提交PR前的自检清单

• 文档描述与当前仓库代码、目录和脚本一致。
• Markdown表格、代码块、标题层级和列表格式正确。
• 相对链接和图片路径可以从当前文档位置正确跳转。
• 命令示例可执行，或已明确说明仅作为示例。
• API函数原型、参数、返回值与公开头文件一致。
• 样例说明已标注前置条件、构建运行方式和验证方式。
• 新增依赖已同步更新三方软件清单和Notice。
• 尚未合入代码或文档的能力，没有提前描述为已支持能力。

资料体系与链接关系

asc-comm资料通过入口文档、指南、API参考和样例说明形成导航关系。新增或修改文档时，应遵循“谁提到其他文档负责的内容，谁添加链接”的原则。

README.md ──文档入口──→ docs/README.md
          ──快速上手──→ docs/quick_start.md
          ──构建测试──→ docs/zh/guide/build_and_test.md
          ──API参考───→ docs/zh/api/README.md
          ──样例入口──→ examples/README.md

docs/README.md ──快速上手──→ docs/quick_start.md
               ──使用指南──→ docs/zh/guide/hcomm_usage.md
               ──构建测试──→ docs/zh/guide/build_and_test.md
               ──API参考───→ docs/zh/api/README.md
               ──样例入口──→ examples/README.md

docs/zh/guide/ ──首次引入API──→ docs/zh/api/README.md
                ──涉及样例────→ examples/README.md

docs/zh/api/ ───使用流程──→ docs/zh/guide/hcomm_usage.md
              ───调用示例──→ examples/aicore/hcomm/01_hcomm_write_read_nbi/README.md

更多信息

• API文档贡献指南：api_contributing.md
• asc-comm贡献指南：CONTRIBUTING.md