Go AST 里注释位置与代码节点为什么可能错开

Go AST 里出现“注释位置和代码节点对不上”，通常不是解析器把行号算错了，而是把两个不同概念混在了一起：File.Comments 是文件中按出现顺序保存的全部注释，Doc、Comment 才是部分节点上的直接关联。游离注释没有必须归属的节点，因此它可能位于某个声明之外。

官方地址：https://pkg.go.dev/go/ast

排查时先用同一个 token.FileSet 把 token.Pos 转成文件、行、列，再分别比较注释范围、节点范围和整个文件范围。不要拿 File.End() 当成源码文件的最后一个字节。

先确认 File.Comments 保存的到底是什么

parser.ParseComments 开启后，ast.File.Comments 会收集该文件中按词法顺序出现的 CommentGroup。其中，声明前的文档注释通常会出现在声明的 Doc 字段，字段或函数体附近的注释可能出现在某个节点的 Comment 字段，但这不表示数组里的每个元素都会有一个唯一的宿主节点。

package main

import (
	"fmt" // 这个注释靠近 ImportSpec，但仍属于 File.Comments
	"go/ast"
	"go/parser"
	"go/token"
)

func dumpComments(src string) {
	fset := token.NewFileSet() // 让本文件的 token.Pos 能还原为行列
	file, err := parser.ParseFile(fset, "demo.go", src, parser.ParseComments)
	if err != nil {
		fmt.Println(err) // 解析失败时不要继续读取不完整的 AST
		return
	}
	for _, group := range file.Comments {
		start := fset.Position(group.Pos()) // 注释起点属于同一个文件集
		end := fset.Position(group.End())   // 结束位置用于判断覆盖范围
		fmt.Printf("%s-%s: %s\\n", start, end, group.Text())
	}
}

这里的关键不是把每条注释强行贴到最近的声明上，而是先保留它的真实位置。文件顶部注释可能早于 File.Pos()，文件末尾注释也可能晚于 File.End()；两者都仍然是文件注释。

File.Pos 和 File.End 不等于整个文件边界

ast.File.Pos() 返回 package 关键字的位置，ast.File.End() 返回最后一个声明的结束位置；空文件或只有包名的特殊情况还可能让这个范围不完整。Go 当前 AST 还提供始终有效的 FileStart 和 FileEnd，它们才适合表示整个文件的起止范围。

因此，下面三种比较不要混用：

例如，文件顶部的版权注释可能位于 File.Pos() 之前，而最后一个函数后的说明注释可能位于 File.End() 之后。它们在范围上“错开”，并不代表位置无效。

用共享 token.FileSet 解释跨文件位置

token.Pos 本质上是文件集中的位置编号，不是独立携带文件名、行号和列号的结构。解析多个文件时，应该复用一个 FileSet，再用 fset.Position(pos) 或 fset.File(pos) 还原位置。如果每个文件各建一个 FileSet，两个文件里的同一个数字不能直接比较。

func locate(fset *token.FileSet, file *ast.File) {
	for _, decl := range file.Decls {
		start := fset.Position(decl.Pos()) // 声明起点要用当前文件集解释
		end := fset.Position(decl.End())   // End 是节点语法范围的末端
		fmt.Printf("decl: %s -> %s\\n", start, end)
	}
	for _, group := range file.Comments {
		pos := fset.Position(group.Pos()) // 可见文件名、行号和列号
		fmt.Printf("comment: %s\\n", pos)
	}
}

实际排查可以先记录三类数据：注释的起止位置、最近节点的起止位置、以及 fset.File(pos).Name() 返回的文件名。这样能快速区分“注释确实在节点范围外”和“位置编号来自不同文件集”这两种完全不同的问题。

修改 AST 时，关联关系要单独维护

直接关联的文档注释可以从节点的 Doc 字段看到，声明或字段尾部注释可能在 Comment 字段；其余注释是 free-floating。需要重排、删除或插入节点时，不能只改 file.Decls，还要决定邻近的 File.Comments 是否一起移动或删除。

如果需求是“找出某节点附近可能属于它的注释”，可以使用 ast.NewCommentMap(fset, file, file.Comments) 生成注释映射。但这是一种基于位置和语法结构的关联结果，不是编译器赋予的永久所有权；对 AST 做结构性改动后，应重新计算或同步调整映射。

打印修改后的树时，go/printer 和 go/format 会根据位置把注释穿插回令牌之间。节点被移动而注释位置没动，就可能出现注释跑到另一段代码旁边的现象。稳妥做法是：先保存节点与注释关系，再一起更新节点范围和注释位置，最后交给打印器输出。

常见问题

为什么 File.Comments 里有注释，但函数的 Doc 是 nil？

因为 File.Comments 保存的是文件内全部注释，而 Doc 只表示直接关联到该节点的文档注释。游离注释或无法按当前语法位置归属的注释不会自动成为函数的 Doc。

File.End() 为什么比最后一行注释更早？

File.End() 以最后一个声明为边界，不以物理文件最后一个字节为边界。需要覆盖整个源文件时，使用 FileStart 和 FileEnd，再单独处理 Comments。

多个文件的 Pos 可以直接比较吗？

只有这些文件使用同一个 token.FileSet 时，比较才有明确含义。不同文件集中的 Pos 数字不能当作统一坐标。