现象

math/log/op_api/aclnn_log2.h 里 aclnnInplaceLog2 的 @param 注释只列 3 种 dtype，且把 selfRef 角色标成 [in]：

@param [in] selfRef(aclTensor*): 数据类型支持FLOAT、FLOAT16、BFLOAT16（910B支持），

资料（math/log/docs/aclnnLog2&aclnnInplaceLog2.md L256）与实现都支持 6 种，角色是输入/输出（原地写回）。实机核对（A2 910B2 / CANN 9.2.0，aclnn 两段式直调，逐个 dtype 换 aclDataType）：

期望

注释与资料 L256 对齐：数据类型支持FLOAT、FLOAT16、DOUBLE、COMPLEX64、COMPLEX128、BFLOAT16，角色写 [in,out]。

环境

• 硬件：Atlas A2 训练系列（Ascend 910B2）；软件：CANN 9.2.0
• 仓与提交：cann/ops-math master af636ea0（git fetch 后核对，缺陷仍在）

复现步骤

1. 在仓根运行 python3 check_hdr_dtype.py --repo-root .（只读两个文件，不需要 NPU）。
2. 看输出末尾两行 [DEFECT]：漏列 COMPLEX128、COMPLEX64、DOUBLE；角色写成 [in]。
3. 进程退出码为 1。

复现脚本

#!/usr/bin/env python3
"""断言：aclnn_log2.h 的 selfRef 注释 dtype 列表 == 资料 inplace 参数表 dtype 列表。
用法: python3 check_hdr_dtype.py --repo-root <仓根>；退出码 0=一致 1=缺陷 2=无法判定。"""
import os
import re
import sys
argv = sys.argv[1:]
root = "."
for i, a in enumerate(argv):
    if a in ("--repo-root", "--root"):
        root = argv[i + 1] if i + 1 < len(argv) else "."
        break
else:
    if argv and not argv[0].startswith("-"):
        root = argv[0]
hdr = os.path.join(root, "math/log/op_api/aclnn_log2.h")
doc = os.path.join(root, "math/log/docs/aclnnLog2&aclnnInplaceLog2.md")
for p in (hdr, doc):
    if not os.path.exists(p):
        print("[SKIP] 找不到 %s（请把仓根作为第一个参数传入）" % p)
        sys.exit(2)
htext = open(hdr, encoding="utf-8", errors="ignore").read()
m = re.search(r"@param\s*\[([^\]]*)\]\s*selfRef\(aclTensor\*\):\s*数据类型支持([^，,]+)", htext)
if not m:
    print("[SKIP] 头文件里没找到 aclnnInplaceLog2 的 selfRef @param 注释")
    sys.exit(2)
role = m.group(1).strip()
raw = re.sub(r"[（(][^）)]*[）)]", "", m.group(2))   # 去掉「（910B支持）」这类括注
comment = {t.strip() for t in re.split(r"[、,，]", raw) if t.strip()}
dtext = open(doc, encoding="utf-8", errors="ignore").read()
sec = dtext.split("## aclnnInplaceLog2GetWorkspaceSize", 1)[-1].split("## aclnnInplaceLog2", 1)[0]
mrow = re.search(r"<td>selfRef（aclTensor\*）</td>(.*?)</tr>", sec, re.S)
if not mrow:
    print("[SKIP] 资料里没找到 aclnnInplaceLog2GetWorkspaceSize 的 selfRef 参数行")
    sys.exit(2)
doc_set = set()
for cell in re.findall(r"<td[^>]*>(.*?)</td>", mrow.group(1), re.S):
    plain = re.sub(r"<[^>]+>", "", cell).strip()
    if "FLOAT" in plain and "、" in plain:
        doc_set = {t.strip() for t in re.split(r"[、,，]", plain) if t.strip()}
if not doc_set:
    print("[SKIP] 资料 selfRef 行里没解析出 dtype 列表")
    sys.exit(2)
print("注释 dtype(%d): %s" % (len(comment), "、".join(sorted(comment))))
print("资料 dtype(%d): %s" % (len(doc_set), "、".join(sorted(doc_set))))
print("注释角色: [%s]" % role)
rc = 0
missing = sorted(doc_set - comment)
if missing:
    print("[DEFECT] 头文件注释漏列 %s —— 资料与实现均支持这 %d 种 dtype"
          % ("、".join(missing), len(missing)))
    rc = 1
if role == "in":
    print("[DEFECT] selfRef 注释角色写成 [in]，资料写「输入/输出」（原地写回），会让人以为只读")
    rc = 1
if rc == 0:
    print("OK：注释与资料一致")
sys.exit(rc)

实测输出（仓根 af636ea0 实跑）：

注释 dtype(3): BFLOAT16、FLOAT、FLOAT16
资料 dtype(6): BFLOAT16、COMPLEX128、COMPLEX64、DOUBLE、FLOAT、FLOAT16
注释角色: [in]
[DEFECT] 头文件注释漏列 COMPLEX128、COMPLEX64、DOUBLE —— 资料与实现均支持这 3 种 dtype
[DEFECT] selfRef 注释角色写成 [in]，资料写「输入/输出」（原地写回），会让人以为只读

退出码 1。

影响

1. 按注释选型会漏掉 DOUBLE / COMPLEX64 / COMPLEX128 三种真实可用的 dtype，用户会改用不需要的类型转换。
2. 角色标成 [in] 会让读者以为 selfRef 只读，与资料参数表「输入/输出」冲突。

建议

1. 改为 @param [in,out] selfRef(aclTensor*): 数据类型支持FLOAT、FLOAT16、DOUBLE、COMPLEX64、COMPLEX128、BFLOAT16，支持非连续的Tensor，数据格式支持ND，selfRef也是输出结果。
2. 同文件 aclnnLog2（非 inplace）的 self/out 注释只列 FLOAT、FLOAT16，属另一个接口，另开一条。