[Feature]: 代码注释-DrivingSDK-AtomGit

感谢您此前对该任务的关注与支持！
由于上一位认领者暂未继续推进该任务，目前该任务已重新开放。根据此前的候选顺序，我们希望优先邀请您参与该任务。
如您目前仍有意愿认领，请在5个工作日内回复确认并参考https://gitcode.com/Ascend/DrivingSDK/issues/215社区任务池加入微信群聊，并简要说明预计开始时间或初步推进计划。确认后，我们将为您保留任务，并提供必要的背景资料和支持。
如您近期时间安排不便，也请直接告知，我们将继续顺延联系其他候选贡献者，不会影响您后续参与其他社区任务。
再次感谢您对昇腾开源社区的关注，期待与您合作！

sanyu

8月21日评论：

领取该任务

M mrlw2026成员

8月21日删除了label：resolved

M mrlw2026成员

8月21日重新打开了 issue

mrlw2026成员

8月21日评论：

领取该任务

@A431500288

你好一个人最多同时接3个任务你可以选择放弃一个任务可以在任务issue区下评论放弃任务

sanyu

8月28日评论：

放弃该任务

mrlw2026成员

8月28日评论：

认领这个任务

@2401_88152875

感谢您此前对该任务的关注与支持！
由于上一位认领者暂未继续推进该任务，目前该任务已重新开放。根据此前的候选顺序，我们希望优先邀请您参与该任务。
如您目前仍有意愿认领，请在5个工作日内回复确认并参考[Roadmap] 社区任务池社区任务池加入微信群聊，并简要说明预计开始时间或初步推进计划。确认后，我们将为您保留任务，并提供必要的背景资料和支持。
如您近期时间安排不便，也请直接告知，我们将继续顺延联系其他候选贡献者，不会影响您后续参与其他社区任务。
再次感谢您对昇腾开源社区的关注，期待与您合作！

onion-111

8月28日评论：

认领这个任务

Yhw050920

8月29日评论：

认领这个任务

mrlw2026成员

9月1日评论：

认领这个任务

@onion-111

感谢您此前对该任务的关注与支持！
由于上一位认领者暂未继续推进该任务，目前该任务已重新开放。根据此前的候选顺序，我们希望优先邀请您参与该任务。
如您目前仍有意愿认领，请在5个工作日内回复确认并参考https://gitcode.com/Ascend/DrivingSDK/issues/215 社区任务池加入微信群聊，并简要说明预计开始时间或初步推进计划。确认后，我们将为您保留任务，并提供必要的背景资料和支持。
如您近期时间安排不便，也请直接告知，我们将继续顺延联系其他候选贡献者，不会影响您后续参与其他社区任务。
再次感谢您对昇腾开源社区的关注，期待与您合作！

onion-111

9月1日评论：

认领这个任务

@onion-111

感谢您此前对该任务的关注与支持！
由于上一位认领者暂未继续推进该任务，目前该任务已重新开放。根据此前的候选顺序，我们希望优先邀请您参与该任务。
如您目前仍有意愿认领，请在5个工作日内回复确认并参考https://gitcode.com/Ascend/DrivingSDK/issues/215 社区任务池加入微信群聊，并简要说明预计开始时间或初步推进计划。确认后，我们将为您保留任务，并提供必要的背景资料和支持。
如您近期时间安排不便，也请直接告知，我们将继续顺延联系其他候选贡献者，不会影响您后续参与其他社区任务。
再次感谢您对昇腾开源社区的关注，期待与您合作！

@mrlw2026
确认参加。微信群二维码过期了，请问要怎么获取背景资料和支持

onion-111

9月14日评论：

DrivingSDK 核心代码注释实践文档

过程

本次新增英文注释pr使用Codex+GPT-5.6 Sol完成。不额外借助特定 SKILL时，注释范围一度扩大到 324 个代码文件、842 行新增注释。逐条评审后发现以下问题：

把循环、公式、转置、初始化和同步指令重新翻译成自然语言，注释没有提供新信息；
对 ping-pong slot、UB、同步阶段、20 KiB 等实现细节作了缺少代码或文档证据的解释；
只处理被指出的单行，没有及时检查同类模式，导致相同的 SetAtomicAdd、SetFlag 等代码采用不同注释标准；
注释表述有时不完整，例如只说明 point gradient，实际同一原子写约束也适用于 center gradient；

根据这些问题，后续在本地新增了 .agents/skills/drivingsdk-code-comment-generation/SKILL.md，并用它重新审查注释。主要方法是：

以算子为审查单位，从 docs/en/api/README.md 出发，关联检查 Python、C++、Host tiling、Device kernel 和测试；
先把候选分为“保留、删除、已有位置覆盖、无法确认”，再修改代码；
只有同时满足“代码和 API 无法直接推出”“改错会造成实质风险”“能用一句话说明原因和后果”时才保留；
优先解释跨层布局、索引与元数据生命周期、原子写初值、多核同步、对齐写回和算法正确性依赖的关键约束；
对同类模式做一致性检查，同一事实只在最合适的位置说明一次；每个函数、关键代码块、文件或算子最多保留 5 条；
不注释普通控制流、显而易见的操作和 API 已说明的内容；证据不足的实现意图不作猜测。

该 skill 只用于辅助筛选和复审，没有作为最终交付提交，SKILL.md 未提交。最终提交只包含算子源码中的注释调整。

结果

修改：55 个文件
新增：62 行高价值注释
删除：5 行低信息旧注释
代码语义变化：0

层次	文件数	新增注释
Kernel / Host	14	14
C++ 桥接层	20	24
Python / Module	21	24
合计	55	62

Git 原始统计为 63 行增加、6 行删除。额外的一增一删来自 boxes_operator_utils.h：一行“代码 + 尾注释”被拆成独立注释和原代码，实际新增注释仍为 62 行。

涉及的算子与内容

布局与接口契约：CartesianToFrenet1、VoxelToPoint、AssignTarget、Gaussian、GridSampler2d/3d、MaxPool2d、PointsInBox/All、RoiAlignRotatedV2、RotatedIoU、ScatterAdd、DeformConv2d、FusedBiasLeakyReLU、AddRelu。注释说明 field-major、NCHW/NHWC、对齐通道、原地别名和历史后端布局。
原子写、初始化与同步：BEVPoolV3、DynamicScatter、GeometricKernelAttention、PixelGroup、VoxelPoolingTrain、GraphSoftmax、GroupPoints、IndexSelect、MultiScaleDeformableAttn、AssignScoreWithK、DeformableAggregation。注释说明输出为何必须清零、何时必须 SyncAll，以及对齐原子写为何要清空其他 lane。
排序、索引与元数据：RoiPointPool3d、HardVoxelize、ScatterMax、SparseConv、BEVPool/BEVPoolV2、BorderAlign、DynamicScatter 和 NMS 系列。注释说明联合排序、前后向分组差异、映射复用条件、固定长度输出和原始索引恢复。
算法正确性依赖的关键约束：BoxesOverlapBEV、CalAnchorsHeading、DrawGaussianToHeatmap、DiffIoURotated、FurthestPointSampling、BoxIoU、NMS3DOnSight、UniqueVoxel。注释说明候选顶点 padding、heading 有效性、高斯取最大值、共享角点去重、Min 哨兵、角度方向、负平方阈值和 packed ID 按位排序。同一约束在通用实现与 arch35 实现中保持一致，例如 DrawGaussianToHeatmap 的重叠区域取最大值，以及 DynamicScatterMax 初始化完成后再执行原子最大值。

未保留的候选

无法可靠确认：缺少代码、测试或文档证据的魔数来源、调度选择、历史兼容原因和性能动机；
重复 API 文档：参数、shape、dtype、返回值和算子总体功能；
复述代码：例如“执行转置”“初始化输出”“等待同步”；
已有位置覆盖：同一事实已在更合适的共同入口说明。

没有高价值注释仅因数量上限而放弃；上限主要用于合并重复表达。非算子通用代码未纳入本次最终提交和 62 行统计。

验证

git diff-tree --check 通过；
21 个 Python 文件去除注释后 AST 一致；
34 个 C/C++ 文件剥离注释后代码 token 一致；
未发现表达式、控制流、函数签名或调用参数变化。

结论：本次提交只增加维护所需的实现约束说明，没有改变算子行为。

M mrlw2026成员

9月15日 issue状态由 TODO 改变为 DONE

M mrlw2026成员

9月15日关闭了 issue

ascend-robot成员

9月15日添加了label：resolved

O onion-111

9月24日关联了pull request：docs: 补充核心算子关键实现约束注释