Go parser.ParseComments 怎样让 AST 保留源码注释

使用 Go 的 go/parser 分析源码时，如果希望 AST 里保留注释，需要在 parser.ParseFile 的 mode 参数中加入 parser.ParseComments。解析成功后，可以从 ast.File.Comments 读取全部注释组，也可以从函数、类型等声明节点的 Doc 字段读取与声明关联的文档注释。

先用一个小工具解析带注释的 Go 源码

假设我们要做一个简单的源码目录索引器：它需要读取函数名，也要保留函数上方的注释。解析入口是 parser.ParseFile，其中 token.NewFileSet() 用于保存源码位置，第四个参数则是解析模式。

package main

import (
	"fmt"
	"go/ast"
	"go/parser"
	"go/token"
)

func main() {
	const source = `package demo

// Add 返回两个整数的和。
func Add(a, b int) int { return a + b }
`

	fset := token.NewFileSet()
	// ParseComments 是关键开关；没有它，AST 不会保留源码注释。
	file, err := parser.ParseFile(fset, "demo.go", source, parser.ParseComments)
	if err != nil {
		// 源码有语法错误时先报告错误，避免把不完整结构当成完整结果。
		panic(err)
	}

	// 通过 AST 遍历函数声明，同时读取声明关联的 Doc 注释。
	ast.Inspect(file, func(node ast.Node) bool {
		fn, ok := node.(*ast.FuncDecl)
		if !ok {
			return true
		}
		fmt.Printf("函数=%s，文档=%q\n", fn.Name.Name, fn.Doc.Text())
		return true
	})
}

这里真正改变结果的是 parser.ParseComments。它不是独立的解析函数，而是 parser.Mode 中的一个标志位，可以和其他模式通过按位或组合。

ParseComments 会把哪些注释放进 AST

开启注释解析后，ast.File.Comments 保存文件中的注释组。注释组由一个或多个相邻的 *ast.Comment 组成，工具可以按源码位置遍历它们。对于紧邻声明的文档注释，函数声明、类型声明和字段等节点通常还会通过 Doc 字段提供更直接的关联。

两种读取方式用途不同：File.Comments 适合做全文注释索引、格式化或保留原始顺序；声明节点的 Doc 适合生成“函数名—说明”这类结构化结果。

func printComments(file *ast.File, fset *token.FileSet) {
	// File.Comments 覆盖整个文件，适合保留注释的源码位置。
	for _, group := range file.Comments {
		pos := fset.Position(group.Pos())
		fmt.Printf("%s: %s", pos, group.Text())
	}

	// Doc 只表示当前声明关联的文档注释，不等于文件中的全部注释。
	for _, decl := range file.Decls {
		switch node := decl.(type) {
		case *ast.FuncDecl:
			if node.Doc != nil {
				fmt.Printf("func %s: %s", node.Name.Name, node.Doc.Text())
			}
		case *ast.GenDecl:
			if node.Doc != nil {
				fmt.Printf("declaration: %s", node.Doc.Text())
			}
		}
	}
}

注意同一段文档注释既可能出现在文件级注释集合中，也会通过节点的 Doc 字段被引用。做统计时要确定唯一口径，否则容易重复计数。

mode=0 为什么看不到注释

如果把解析调用写成 parser.ParseFile(fset, name, src, 0)，解析器仍然会建立包名、声明和表达式等语法节点，但不会按 ParseComments 模式把注释加入 AST。于是 file.Comments 为空，声明节点的 Doc 也无法提供预期文本。

这不是注释内容被清洗掉，而是调用方没有选择保留注释的解析模式。源码分析工具可以根据用途选择：

组合 ParseComments 与错误处理

源码索引器经常面对用户正在编辑、尚未保存完整的文件。ParseFile 返回错误时，结果可能是部分 AST。若任务是编辑器提示，可以继续读取安全的部分节点；若任务是发布文档，则通常应该中止并等待源码修复。

func parseForIndex(filename string, src []byte) (*ast.File, *token.FileSet, error) {
	fset := token.NewFileSet()
	// AllErrors 让工具更完整地收集语法错误，ParseComments 保留文档信息。
	file, err := parser.ParseFile(fset, filename, src, parser.ParseComments|parser.AllErrors)
	if err != nil {
		// 返回部分 AST 供上层决定是否展示，但不把错误静默吞掉。
		return file, fset, fmt.Errorf("解析 %s 失败: %w", filename, err)
	}
	return file, fset, nil
}

这个函数把“结构结果”和“解析错误”一起交给上层，避免调用方误以为返回非 nil AST 就代表源码完整合法。

落地时的检查清单

• 是否在需要注释的每一次 ParseFile 调用中加入了 parser.ParseComments？
• 是要读取全部注释，还是只读取声明的 Doc？先确定统计口径。
• 是否保留了 token.FileSet，以便把注释和 AST 节点转换回文件名、行号和列号？
• 解析错误时，业务是使用部分 AST，还是必须等待完整源码？

常见问题

ParseComments 会把注释变成普通语句吗？

不会。注释仍然是 AST 中的注释节点和文档字段，不会参与 Go 表达式或语句求值。

只读取函数文档时还需要遍历 File.Comments 吗？

不一定。只做声明文档索引时读取函数或类型节点的 Doc 更直接；需要保留文件中游离注释、顺序或精确位置时，再读取 File.Comments。

ParseComments 和 AllErrors 能一起用吗？

可以。它们都是解析模式标志，可以用按位或组合；一个控制注释保留，一个控制错误收集范围。