API文档贡献指南

本文档说明asc-comm API文档的补充和修改要求。新增或修改公开API时，应同步更新对应API文档、使用说明、样例和测试说明。

适用范围

适用于docs/zh/api/下的公开API参考文档，以及与API行为直接相关的使用说明和样例文档。

文档结构

新增API文档建议包含以下章节：

• 功能说明：说明API的用途、使用场景和适用范围。
• 函数原型：保持与公开头文件中的声明一致。
• 参数说明：列出参数名称、输入输出属性、单位和约束。
• 模板参数：模板接口需说明默认值、适用协议或平台差异。
• 返回值：说明成功、失败和常见失败条件。
• 约束说明：说明调用顺序、地址要求、对齐要求、协议支持范围和配套资源依赖。

编写要求

• API名称、参数名称、默认模板参数和返回值必须以代码为准。
• 文档中涉及协议能力时，需要明确支持范围，例如COMM_PROTOCOL_ROCE、COMM_PROTOCOL_UBC_CTP。
• 若接口涉及通信通道、注册内存或算子工程能力，需要在约束说明中写清资源准备要求。
• 示例代码应能反映可验证的调用方式；无法独立运行的片段需要明确说明前置条件。
• 修改API行为时，应同步更新docs/zh/api/README.md、相关guide、examples和UT说明。

检查建议

提交前建议完成以下检查：

• 确认文档中的函数原型与include/下公开头文件一致。
• 确认链接路径可从当前文档位置正确跳转。
• 确认新增约束与现有UT或实现逻辑一致。
• 若新增三方依赖或直接打包内容，同步检查三方软件清单和Notice。