Go ast.NewCommentMap 结果为空为什么要先检查解析模式

ast.NewCommentMap 只关联调用方传入的注释组，不会重新扫描源文件。如果解析时没有启用 parser.ParseComments，通常作为第三个参数传入的 file.Comments 就没有注释组，结果为空是正常的输入结果。因此应先检查解析模式和注释列表，再排查节点关联规则。

官方文档：https://pkg.go.dev/go/parser#Mode；注释映射：https://pkg.go.dev/go/ast#NewCommentMap。

先看注释有没有进入 AST

假设一个源码整理工具读到了 var 声明，却怎么也找不到旁边的说明文字。这时我会先看 ParseFile 的 mode，而不是先调整 NewCommentMap 的根节点。源码字符串里有注释，并不代表解析结果已经保留了注释。

ParseComments 控制注释进入 AST。NewCommentMap 的三个参数分别提供位置表、关联范围的语法根节点和注释组列表。它没有文件名或源码内容参数，职责是建立关系，而不是补做词法扫描。

用两种解析模式对照输入

下面的原创示例只改变解析模式，用同一源码比较 file.Comments 与映射键的数量。代码没有执行，文中不提供冒充实际日志的输出。两次解析分别创建位置表，并始终把各自的表与 AST 配对。

package main

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

func main() {
 // 同一源码分别演示不保留与保留注释的解析方式。
 const source = `package sample
// Count 表示计数。
var Count = 1 // 初始计数
`
 modes := []struct {
  name string
  mode parser.Mode
 }{
  {"未开启注释", parser.SkipObjectResolution},
  {"保留注释", parser.SkipObjectResolution | parser.ParseComments},
 }
 for _, item := range modes {
  // 每份 AST 与它自己的 FileSet 配对，不混用位置记录。
  fset := token.NewFileSet()
  file, err := parser.ParseFile(fset, "sample.go", source, item.mode)
  if err != nil {
   fmt.Println("解析失败：", err)
   return
  }
  comments := ast.NewCommentMap(fset, file, file.Comments)
  fmt.Printf("%s: 注释组=%d 关联节点=%d\n",
   item.name, len(file.Comments), len(comments))
 }
}

第一种模式没有 ParseComments，不保留这里的注释。第二种模式使用按位或叠加 ParseComments，会保留声明前和行尾的注释组。模式位是可以组合的，不应为了保留注释而不小心覆盖已有的其他模式配置。

SkipObjectResolution 跳过已弃用的标识符对象解析，和是否保留注释是两件事。也不要把 AllErrors 当成注释开关：它影响错误报告范围，不负责把注释加进 AST。

保留同一位置上下文建立关联

确认注释组非空后，再看 FileSet 是否对应当前 AST，第三个参数是否真的传入 file.Comments，以及根节点是否是预期分析范围。混用不同解析任务的位置值，会让关联依赖的位置解释失去一致性。

CommentMap 根据注释组与语法节点的行位置进行关联，并倾向于关联到较大的节点。例如赋值语句后的行尾注释，可以归到整条赋值语句，而不是最后一个操作数。不能因为在某个细小表达式键下查不到注释，就判断整个映射为空。

如果先改写或删除节点，再用旧节点地址查映射，也可能与预期不同。对重写工具，我会保留明确的关联更新策略；NewCommentMap 不是持续监听 AST 变化的对象。它只能基于给定节点与注释位置建立当前关系。

区分空映射与没有文档注释

len(CommentMap) 统计关联节点的数量，不是注释文本行数，也不是注释组数量。同一个节点可以关联多组注释，读取时应使用对应的组列表。文件里的独立注释、行尾注释与声明的 Doc 字段，也不应被混为一种数据。

解析返回错误时，ParseFile 可能给出部分 AST，工具必须说明是否接受部分结果。不要忽略错误后，把缺失注释都归因于模式。需要完整文件信息时，也要注意 PackageClauseOnly、ImportsOnly 这样的选项会限制解析范围。

常见问题：源文件没有注释时映射为空正常吗？正常。开启 ParseComments 就能获得作者的语义关联吗？不能，它按位置规则组织，不理解自然语言含义。只提取注释文字需要建 map 吗？不一定，直接遍历 file.Comments 更贴近需求；需要知道注释关联哪个语法节点时再建映射。