需手动构造ast.CommentGroup并赋值给funcDecl.Doc字段，注意注释格式、空行限制及导出函数首字母大写要求，修改后须用astutil.Insert或替换节点并重新生成源码。
用 ast.NewCommentGroup 插入文档注释节点
Go 的 AST 不会自动把已有注释“挂”到函数节点上，除非它紧贴在函数声明前且格式规范（// 或 /* */ 且无空行）。要给函数自动加文档注释，得手动构造 ast.CommentGroup 并赋值给函数节点的 Doc 字段。
注意：不能直接改 funcDecl.Doc 后就完事——AST 修改后必须重新生成 Go 源码，否则只是内存结构变化。常用做法是用 golang.org/x/tools/go/ast/astutil 的 Insert 或直接替换整个 FuncDecl 节点。
-
ast.CommentGroup的List字段需填入*ast.Comment切片，每条注释以"// "开头（注意空格），末尾不换行 - 若函数已有
Doc（比如已有注释），先判断是否为空再决定覆盖还是跳过 - 注释内容里避免硬编码包名或函数签名；建议从
funcDecl.Name.Name和funcDecl.Type.Params动态提取参数名
处理导出函数和非导出函数的差异
Go 文档工具（如 go doc、godoc）只显示首字母大写的导出函数的文档注释。所以自动补注释时，要区分对待：
- 导出函数（
funcName[0] >= 'A' && funcName[0] ）：补标准三行格式：<code>// FuncName does X.+ 空行 +// ... - 非导出函数：可补简短单行注释，如
// helper: sorts in-place，避免被go doc误抓取为公开 API - 若函数名含下划线（如
init_db），即使首字母小写，也可能是测试或初始化逻辑——这类建议统一跳过，不强制加文档
用 astutil.Apply 安全遍历并修改函数节点
直接递归遍历 ast.File 容易漏掉嵌套函数或 panic（比如 funcDecl.Type 为 nil）。推荐用 astutil.Apply，它能稳定遍历所有节点，并支持在进入/离开时插入逻辑。
立即学习“go语言免费学习笔记（深入）”；
关键点：
- 在
pre钩子中匹配*ast.FuncDecl，检查funcDecl.Doc == nil且函数体非空（funcDecl.Body != nil） - 构造新
ast.CommentGroup后，**必须返回修改后的节点**（即return funcDecl, true），否则修改不生效 - 不要在
pre中修改父节点（如*ast.File），否则可能破坏遍历顺序；所有变更集中在当前*ast.FuncDecl
示例片段：
astutil.Apply(fset, file, func(cursor *astutil.Cursor) bool {
if fd, ok := cursor.Node().(*ast.FuncDecl); ok && fd.Doc == nil && fd.Body != nil {
doc := &ast.CommentGroup{
List: []*ast.Comment{{Text: "// " + fd.Name.Name + " implements ..."}},
}
fd.Doc = doc
return true
}
return true
}, nil)生成代码时保留原有格式和位置
用 format.Node 直接输出 AST 会丢失原始缩进、空行和注释位置。想“原样插入”，得用 golang.org/x/tools/go/format 或更稳妥的 gofmt 命令重写文件，但前提是先将修改后的 AST 写回源码字符串。
- 优先用
printer.Config{Mode: printer.UseSpaces | printer.TabIndent, Tabwidth: 4}控制缩进风格，与项目一致 - 若原文件用了
gofmt -s（简化模式），生成时也要开启printer.SourcePos并确保fset正确，否则行号错乱 - 最保险的做法：把修改后的 AST 格式化为字符串 → 用
diff对比原文件 → 只替换函数声明所在行范围（需提前记录fset.Position(funcDecl.Pos())）
真正难的不是加那几行 //，而是让新加的注释看起来像人写的：缩进对齐、动词用现在时、不出现 “this function” 这种冗余主语——这些没法靠 AST 自动推断，得靠模板或人工 review。
