Closed
[Documentation|文档反馈]: matmul 设计总结存在"待更新/待完善"遗留占位,Padding 抽象适用场景缺失 #594
廖氏如神Add on  Sep 20Closed at  Sep 21
廖氏如神
廖氏如神
Sep 20 Create

问题描述

docs/zh/2_Design/01_kernel_design/04_matmul_summary.md 中存在文档自述未完成的遗留占位:

  • L5:"……其他涉及量化、groupMatmul、后处理等的矩阵乘不在此处总结(新增StreamK等Matmul样例待更新)"
  • L608:PaddingMatrixND、PaddingMatrixBlockND 和 PaddingMatrixNZ 各自的适用场景待完善,泛化上PaddingMatrixNZ更具有优势。

即:文档明确宣称部分内容"待更新 / 待完善",但长期未补齐(非近期改动引入)。

规范依据

《文档写作规范》要求文档内容完整、准确。设计文档中公开声明"待完善"且长期未跟进,会向读者传递"该文档内容可能不可信/不完整"的信号。

影响分析

  1. 关键设计信息缺失:PaddingMatrixND / PaddingMatrixBlockND / PaddingMatrixNZ 是 Padding 前处理的三个核心抽象,文档自述"各自的适用场景待完善"——开发者无法据此判断选型,只能读源码;
  2. 覆盖范围声明不完整:文档开头声明"新增 StreamK 等 Matmul 样例待更新",读者无法确定当前总结的边界是否覆盖自己的场景;
  3. 文档可信度损耗:占位性表述长期存在会让读者对整篇总结的时效性产生怀疑。

修复建议

  1. 补全三个 Padding 抽象的适用场景说明(或至少给出选型对照表);
  2. 更新 L5 的覆盖范围声明,明确当前已覆盖/未覆盖的样例清单;
  3. 若确属计划中的工作项,建议转为跟踪 Issue 并在文档中链接,避免"待完善"字样长期滞留。

问题复现方式

git clone --depth 1 https://gitcode.com/cann/catlass.git
cd catlass

sed -n '5p'    docs/zh/2_Design/01_kernel_design/04_matmul_summary.md   # "待更新"
sed -n '608p'  docs/zh/2_Design/01_kernel_design/04_matmul_summary.md   # "待完善"

影响级别

L2:设计文档关键选型信息缺失(文档自述待完善),影响开发者对 Padding 抽象的正确选用;不影响功能正确性。

likedislike
Ssunhao_hwCollaborators
Sep 21 Assign sunhao_hw as responsible person
sunhao_hwCollaborators
Sep 21 Comments:

感谢开发者的反馈,会尽快对文档进行修改。StreamK会补充库上已有的算法方案,Padding几种模式适用场景由于难以直接量化区分,将推荐开发者自行尝试,并去掉文档中的模糊描述

likedislike
Ssunhao_hwCollaborators
Sep 21 Associated pull request
sunhao_hwCollaborators
Sep 21 Comments:

开发者您好,文档修改已合入,计划关闭此issue,如果有新的问题欢迎新开pr或参与SIG进行讨论

likedislike
Ssunhao_hwCollaborators
Sep 21 Added label: Bug-Report
Ssunhao_hwCollaborators
Sep 21 Added label: resolved
Ssunhao_hwCollaborators
Sep 21 changed custom state from 进行中 to 已完成
Ssunhao_hwCollaborators
Sep 21 Close issue