已合并
[Docs] 优化 docs 资料 #3918
Yuanhao Ji创建于 7月21日
[Docs] 优化 docs 资料 #3918
已合并
Pull Request已成功合入, 合并人@CANN-robot
（感谢 Yuanhao Ji 的贡献）
atomgit-bot
7月21日 评论：
7月21日 评论：
变更摘要
本次 PR 主要对 HCCL 通信库头文件中的 Doxygen 风格注释进行了修正和补充，属于文档优化类变更。改动集中在三个头文件中：更正了 HcclGetRankId 和 HcclCommSymWinRegister 的参数描述错误，补充了内核启动函数的返回值说明，并为 HcommAclrtNotifyWaitOnThread 的 timeOut 参数添加了单位注解。
主要改动
- 修正
HcclGetRankId的参数文档：将@param rankSize更正为@param rank，与函数签名中的实际参数名保持一致。 - 修正
HcclCommSymWinRegister的参数文档：将size参数的类型描述从size_t更正为uint64_t，并将flag参数的合法值从0更正为1。 - 补充内核启动函数的返回值文档：在
HcclKernelLaunchCfgInit相关注释中新增了HCCL_E_PTR（空指针错误，含具体场景）和HCCL_E_PARA（参数argSize超限）的返回值说明，替代了原有的HCCL_E_NOT_SUPPORT描述。 - 补充
HcommAclrtNotifyWaitOnThread参数单位：为timeOut参数添加了单位：毫秒的注释，明确了超时时间的计量单位。
atomgit-bot
7月21日 评论：
7月21日 评论：
代码审查
审查总结
本次 PR 是一个大规模的文档优化变更，涉及 132 个文件，主要改动包括：
C 头文件变更（3 个文件）
- include/hccl/hccl_comm.h：修复了 3 处 doxygen 注释错误（参数名、类型、flag 支持值）
- include/hccl/hccl_launch.h：补充了
HcclAicpuKernelLaunch更详细的返回值说明 - include/hcomm_primitives.h：为
HcommAclrtNotifyWaitOnThread的 timeout 参数补充了单位说明（毫秒）
新增文档（14 个文件）
- 新增数据类型定义文档：
HcclCMDType.md、HcclConn.md、HcclOpP2pDesc.md、HcclP2pKernelParam.md、CcuAddressHandle.md、CcuBufferHandle.md、CcuEventHandle.md、CcuKernelArg.md、CcuLocalAddrHandle.md、CcuRemoteAddrHandle.md、CcuVariableHandle.md、HcommMemHandle.md、HcommResult.md、HcommSocket.md
文档内调用示例新增（6 个文件）
HcclCommActivateCommMemory.md、HcclCommDeactivateCommMemory.md、HcclCommSetMemoryRange.md、HcclCommSuspend.md、HcclCommUnsetMemoryRange.md、HcclGetCommAsyncError.md、HcclGetErrorString.md
文档修复/优化（其余约 110 个文件）
- 修复 Markdown 中
[!NOTE]/[!CAUTION]后缺少空格的格式问题（大量文件） - 术语统一："规约"→"归约"、"主机侧"→"Host侧"、"设备侧"→"Device侧"
- 代码示例修复：
strcpy→strncpy、类型修正（uint32_t→CommTopo）、命名参数语法修正（netLayer=0→0）、未声明变量补充声明 - 为多个 API 文档的参数表补充
HcclComm等类型的链接 - 目录结构调整：
rank_graphs→rank_graph，新增config_mgr、experimental blacklist.txt：移除已不存在的文件src/common/launch_aicpu/launch_aicpu.cc
发现的问题
| 优先级 | 数量 |
|---|---|
| P0 | 0 |
| P1 | 0 |
| P2 | 0 |
| P3 | 2 |
P3 问题明细：
HcclGetCommAsyncError.md：示例代码中asyncError未初始化且未检查 API 返回值HcclCommActivateCommMemory.md：零拷贝示例缺少资源释放步骤提示
整体风险评价：低。 本次变更为纯文档优化，无代码逻辑变更。所有的头文件变更均为 doxygen 注释修正。文档示例中的两个 P3 问题仅为示例代码的健壮性不足，不影响实际 API 使用。
⚠️ 已识别出整体风险，但无法提取行内评论，请参考整体评估。
7月21日 添加了label：cann-cla/yes
CANN-robot
7月21日 评论：
7月21日 评论：
Thanks for your pull-request.
The full list of commands accepted by me can be found at here。
You can get sig-info at here
PR Approval Progress
✅ Congratulations! All modules have met the lgtm and approve requirements.
Module Approval Details
| module | lgtm status | approve status |
|---|---|---|
| blacklist.txt | ✅ 颜业峰, yanzhenghang (2/2) | ✅ 颜业峰 (1/1) |
| docs | ✅ 颜业峰, flyswa, yanzhenghang (3/2) | ✅ 颜业峰, flyswa (2/1) |
| include | ✅ 颜业峰, yanzhenghang (2/2) | ✅ 颜业峰 (1/1) |
| repo-cann/hcomm | ✅ 颜业峰, yanzhenghang (2/2) | ✅ 颜业峰 (1/1) |
💡 Tip:
- Committer can comment
/approveor/lgtm- Commenting
/approveimplies both code review (lgtm) and intent to merge (approve)
CLA Signature Pass
jiyuanhao, thanks for your pull request. All authors of the commits have signed the CLA. 👍
CANN-robot7月21日 将leabclove,yanglianxiang2,ccNeo824,flyswa,chengym,ccl_ligang,linyf950,yanzhenghang,chenliang267,claire8090,yanyefeng,chenhao_,dingweiqin_57,songmingyang,wenxuemin,yangxiaoyuan,laodazhao1,yangshaohua,chenke2026,zhongqin2020,bz_lee,Innoecho,chenyia,temper7620,zhangxp1030,abiggg,lilin_137,lilianlin_hw,hulk1997,ouyangxizi设为评审人
7月21日 将leabclove,yanglianxiang2,ccNeo824,flyswa,chengym,ccl_ligang,linyf950,yanzhenghang,chenliang267,claire8090,yanyefeng,chenhao_,dingweiqin_57,songmingyang,wenxuemin,yangxiaoyuan,laodazhao1,yangshaohua,chenke2026,zhongqin2020,bz_lee,Innoecho,chenyia,temper7620,zhangxp1030,abiggg,lilin_137,lilianlin_hw,hulk1997,ouyangxizi设为评审人
此处折叠了129条消息 查看更多
严正行
7月31日 评论：
7月31日 评论：
/lgtm
严正行
7月31日 评论：
7月31日 评论：
/lgtm
philo
7月31日 评论：
7月31日 评论：
/approve
7月31日 添加了label：lgtmapproved
7月31日 合入了pull request
描述
变更类型
请选择本次引入的变更类型：
关联的Issue
测试
已完成的测试用例和场景：
1.
2.
补充的UT用例：
文档更新
合入检查