Go go/doc.New 怎样从 AST 构建包文档

如果你已经有 Go 的 AST，想把包注释、类型、变量和函数整理成一个可查询的文档模型，核心入口就是 go/doc。已有 *ast.Package 时调用 doc.New；只有若干 *ast.File，或者还要收集 _test.go 中的示例时，使用 doc.NewFromFiles。

官方地址：https://pkg.go.dev/go/doc#New

doc.New 负责从 AST 计算包文档，不负责解析源码。解析由 go/parser 完成，位置关系由同一个 token.FileSet 维护；输入准备错了，后面的文档模型就会缺少注释、示例或正确的文件归属。

一、先分清 New 与 NewFromFiles 的输入

doc.New 的签名是 New(pkg *ast.Package, importPath string, mode Mode) *Package。它接收的是已经按包组织好的 AST，不是文件路径，也不会替你扫描目录。返回的 doc.Package 会把包级注释、包名、导入、文件名和声明整理成字段。

二、解析带注释的源文件

文档提取依赖 AST 中的注释信息，因此解析文件时要打开 parser.ParseComments。下面的辅助函数只负责解析源码文本，重点是让 go/doc 接到带注释的 AST。

package main

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

// parseSource 把源码文本解析为带注释的 AST 文件。
func parseSource(fset *token.FileSet, filename, source string) (*ast.File, error) {
    // ParseComments 保留包注释和声明注释，供 go/doc 后续提取。
    return parser.ParseFile(fset, filename, source, parser.ParseComments)
}

func main() {
    fset := token.NewFileSet()
    source := `// package demo 展示文档提取。
package demo

// Greet 返回问候语。
func Greet(name string) string { return "Hello, " + name }
`
    file, err := parseSource(fset, "demo.go", source)
    if err != nil {
        // 解析失败时立即返回，避免把不完整 AST 交给文档层。
        panic(err)
    }
    fmt.Println(file.Name.Name)
}

FileSet 不只是一个容器。后续如果改用 NewFromFiles，所有文件都应使用同一个 FileSet 解析，这样文档包才能根据位置找到对应的文件名。

三、构建可查询的 Package 文档模型

当你已经有一个 ast.Package，把解析出来的文件放到 Files 映射中，再调用 doc.New。mode 决定提取范围：默认面向导出声明；需要内部声明时再传入 doc.AllDecls。

package main

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

func main() {
    fset := token.NewFileSet()
    source := `// package demo 展示文档提取。
package demo

// Greet 返回问候语。
func Greet(name string) string { return "Hello, " + name }
`
    file, err := parser.ParseFile(fset, "demo.go", source, parser.ParseComments)
    if err != nil {
        // 源码不是合法 Go 文件时，不继续构造包文档。
        panic(err)
    }

    pkg := &ast.Package{
        // 文件名作为 key，便于 doc.New 识别包内文件。
        Name:  file.Name.Name,
        Files: map[string]*ast.File{"demo.go": file},
    }
    docPkg := doc.New(pkg, "example.com/demo", 0)
    fmt.Println(docPkg.Name, docPkg.ImportPath)
    if len(docPkg.Funcs) > 0 {
        // Funcs 保存包级函数的文档记录，而不是函数执行结果。
        fmt.Println(docPkg.Funcs[0].Name, docPkg.Funcs[0].Doc)
    }
}

doc.New 会接管并可能修改传入的 AST。若同一份 AST 还要交给格式化器、重写器或类型分析器，不要把它当作不可变输入；可以提前复制解析结果，或者在需要时使用 doc.PreserveAST 语义。

四、需要示例时用 NewFromFiles

doc.New 本身不能从单独的 *ast.Package 自动填充示例。若要把 _test.go 中形如 ExampleGreet 的示例关联到函数或类型，应把普通源码文件、测试文件和对应的 token.FileSet 一起交给 doc.NewFromFiles。

package main

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

func main() {
    fset := token.NewFileSet()
    files := make([]*ast.File, 0, 2)
    sources := []struct {
        name string
        src  string
    }{
        {"demo.go", `package demo

// Greet 返回问候语。
func Greet(name string) string { return "Hello, " + name }
`},
        {"demo_test.go", `package demo_test

// ExampleGreet 展示 Greet 的用法。
func ExampleGreet() {}
`},
    }
    for _, item := range sources {
        file, err := parser.ParseFile(fset, item.name, item.src, parser.ParseComments)
        if err != nil {
            // 任一文件解析失败都停止组装，避免示例关联出现假结果。
            panic(err)
        }
        files = append(files, file)
    }

    docPkg, err := doc.NewFromFiles(fset, files, "example.com/demo")
    if err != nil {
        // NewFromFiles 会报告文件集合与 FileSet 不匹配等输入问题。
        panic(err)
    }
    fmt.Println(docPkg.Name, len(docPkg.Examples))
}

这里的切片元素使用了 *ast.File，因此必须导入 go/ast。这也是组装最小示例时的常见遗漏：API 调用本身正确，但输入类型所属的包没有补齐。

五、文件集合、构建上下文和 AST 所有权

NewFromFiles 会使用你传入的全部文件，不会替你过滤构建约束。目标平台不同，文件集合也可能不同；在送入文档层前，应按照项目的 GOOS、GOARCH 和构建标签选出匹配文件。

另一个边界是所有权：doc.New 和 doc.NewFromFiles 默认都可能修改 AST。需要在调用后继续使用原始 AST 时，显式考虑 doc.PreserveAST，并把它当成内存和兼容性取舍，而不是随手追加的保险参数。

六、用一张判断清单收口

1. 源码是否用 parser.ParseComments 解析？没有注释就不会有完整文档。
2. 手里是 *ast.Package，还是 []*ast.File？前者用 New，后者用 NewFromFiles。
3. 是否需要测试示例？需要就把符合命名规则的 _test.go 传给 NewFromFiles。
4. 文件是否属于当前构建上下文？不匹配的文件要在进入文档层前过滤。
5. 后续还要复用 AST 吗？需要就考虑 PreserveAST 或复制输入。

这样拆分后，go/doc.New 的职责就很清楚：它不是解析器，也不是完整站点渲染器，而是把已经准备好的 Go AST 整理成包级文档对象。

相关问题

doc.New 和 doc.NewFromFiles 有什么区别？

前者接收 *ast.Package，后者接收文件列表和 *token.FileSet；后者更适合控制文件集合并关联测试示例。

为什么 doc.Package 的 Examples 为空？

常见原因是只调用了 doc.New，或者没有把符合命名规则的 _test.go 文件传给 NewFromFiles。

调用 go/doc 后 AST 被改了怎么办？

把文档提取看成会消费 AST 的操作；后续仍要依赖原树时，使用保留 AST 的模式或在解析阶段准备独立副本。