在 Go 的 go/ast 包中，Doc 指紧邻节点声明前、无空行间隔的连续文档注释（用于生成 godoc），而 Comment 是附属于字段或语法节点本身的行内或行尾注释，二者语义、位置和用途截然不同。
在 go 的 `go/ast` 包中，`doc` 指紧邻节点声明前、无空行间隔的连续文档注释（用于生成 godoc），而 `comment` 是附属于字段或语法节点本身的行内或行尾注释，二者语义、位置和用途截然不同。
在使用 go/parser 解析 Go 源码并遍历 AST 时，准确理解 Doc 和 Comment 的差异，是实现代码分析、自动生成文档或重构工具的关键基础。它们虽同属注释范畴，但在 AST 结构中承担完全不同的角色：
✅ Doc：面向 godoc 的结构化文档注释
- 位置要求严格：必须位于某个 AST 节点（如 TypeSpec、FuncDecl、VarSpec）正上方，且与该节点之间不能有空行；
- 语义明确：专为 godoc 工具设计，用于生成公开 API 文档；
- 类型载体：由 *ast.CommentGroup 表示，内部可包含多行 // 注释（只要连续、无空行）；
- 典型用例：
// A Rect represents a 2D rectangle with integer coordinates.
// It is used extensively in image processing.
type Rect struct {
Min, Max Point
}此处两个 // 行共同构成 Rect 类型的 Doc，将被 godoc 提取为类型说明。
✅ Comment：节点内部的关联性注释
- 位置灵活：出现在字段定义同一行的行尾（// ...），或紧跟在字段后的连续行（无空行）；
- 作用域局部：仅关联到其所在字段（如 Name、Type），不参与 godoc 文档生成；
- 结构相同但语义不同：同样用 *ast.CommentGroup 表示，但 AST 节点（如 TypeSpec）的 Comment 字段专为此类注释保留；
- 典型用例：
type TypeSpec struct {
Doc *CommentGroup // associated documentation; or nil
Name *Ident // type name ← 这行末尾的注释即 Name 字段的 Comment
Type Expr // *Ident, *ParenExpr, ...
Comment *CommentGroup // line comments; or nil
}注意：Name 字段后的 // type name 属于 TypeSpec.Comment，而非 TypeSpec.Doc；它描述的是该字段本身，而非整个 TypeSpec 节点。
⚠️ 关键注意事项
- Doc 和 Comment 均为 *ast.CommentGroup 类型，但不可互换使用——Doc 影响 godoc 输出，Comment 仅作开发辅助；
- 空行是 Doc 的“终止符”：一旦出现空行，后续注释不再被视为当前节点的 Doc；
- CommentGroup.List 存储 *ast.Comment 切片，每个 *ast.Comment 的 Text 字段含完整 // ... 字符串（含空格与 //）；
- 若需提取纯文本内容，建议用 ast.CommentGroup.Text() 方法（自动去除 // 前导空白与 // 符号）；
? 快速验证技巧
可通过 go/printer 或调试打印 AST 节点，观察 Doc 与 Comment 字段是否非空：
fset := token.NewFileSet()
f, _ := parser.ParseFile(fset, "example.go", src, parser.ParseComments)
ast.Inspect(f, func(n ast.Node) bool {
if ts, ok := n.(*ast.TypeSpec); ok {
fmt.Printf("Type %s:\n", ts.Name.Name)
if ts.Doc != nil {
fmt.Printf(" Doc: %q\n", ts.Doc.Text())
}
if ts.Comment != nil {
fmt.Printf(" Comment: %q\n", ts.Comment.Text())
}
}
return true
})掌握 Doc 与 Comment 的边界，不仅能写出更规范的 Go 文档，更能精准控制 AST 遍历逻辑——让静态分析工具真正“读懂”你的注释意图。
