Go doc.NewFromFiles 怎么为多个源码文件生成包文档

我第一次把一个 Go 包的文档从源码里抽出来时，最容易犯的错是只解析目录里的第一个 .go 文件。正确做法是：为同一个包的多个文件共用一个 token.FileSet，逐个得到 *ast.File，再把完整切片交给 doc.NewFromFiles。这样返回的 *doc.Package 才能同时看到包注释、声明和需要关联的测试示例。

官方参考：https://pkg.go.dev/go/doc

为多个源码文件共用 FileSet 并保留注释

先把“文件收集”和“文档汇总”分开。parser.ParseFile 每调用一次就产生一个 AST 文件，但所有文件最好共用同一个 FileSet，这样位置对象仍处于同一坐标集合中。解析模式至少带上 parser.ParseComments，否则包注释和声明注释在后面没有可提取的来源。

func parseFiles(fset *token.FileSet, sources map[string]string) ([]*ast.File, error) {
	// 复用同一个 FileSet，让多个 AST 的位置可以统一管理。
	files := make([]*ast.File, 0, len(sources))
	for filename, source := range sources {
		// ParseComments 保留包注释、声明注释和示例注释。
		file, err := parser.ParseFile(fset, filename, source, parser.ParseComments|parser.SkipObjectResolution)
		if err != nil {
			// 解析失败时保留文件名，调用方才能定位坏文件。
			return nil, fmt.Errorf("parse %s: %w", filename, err)
		}
		files = append(files, file)
	}
	return files, nil
}

示例中的 sources 只是为了突出 API 关系；真实项目可以从目录读取文件。关键不在于遍历方式，而在于传给文档层的切片要覆盖同一包真正需要展示的源码。

调用 NewFromFiles 生成 doc.Package

文件集合准备好后，核心调用只有一处：doc.NewFromFiles(fset, files, importPath)。它返回包文档对象和错误。importPath 是文档对象的包路径标识，不是本地目录路径；如果后面要渲染文档链接，应传入项目实际使用的导入路径。

func buildPackageDoc(fset *token.FileSet, files []*ast.File) (*doc.Package, error) {
	// files 必须是同一包、同一构建上下文下的 AST 文件集合。
	if fset == nil || files == nil {
		return nil, errors.New("file set and files must not be nil")
	}
	// importPath 用真实包路径，便于文档对象识别包和处理链接。
	return doc.NewFromFiles(fset, files, "example.com/project/widget")
}

返回的 doc.Package 中可以读取 Doc、Filenames、Consts、Types、Vars、Funcs 和 Examples。它是“文档模型”，不是 HTML 页面；需要网页或 Markdown 时，再使用 Package.HTML、Package.Markdown 或自定义 Printer。

按构建上下文筛选文件并处理测试示例

NewFromFiles 会使用你传入的全部文件，因此带有不同 GOOS、GOARCH 或 build constraint 的文件不能无条件混在一起。文档工具应先按目标构建上下文选文件，再解析和汇总；否则同名声明、平台专属 API 或不适用的注释可能一起出现在结果中。

需要示例时，把符合范围的 _test.go AST 也加入切片。标准库会根据示例函数名把 ExampleFoo、ExampleFoo_bar 关联到包、类型或函数；命名不符合规则的示例会被跳过。这里的关键是“选择正确的测试文件”，而不是把测试文件当成普通业务文件强行合并。

我会把这层判断写在调用前：文件属于哪个构建上下文、是否应进入文档、是否需要示例，先形成清晰的集合，之后的 NewFromFiles 只负责从集合建立文档模型。

用 Mode 控制 AST 与声明范围

默认结果适合常规公开 API 文档；如果要展示未导出声明，可以传入 doc.AllDecls，需要更多嵌入方法时使用 doc.AllMethods。另一个容易忽略的选项是 doc.PreserveAST：没有它时，NewFromFiles 可能为了节省内存修改 AST；调用方还要继续使用函数体或节点时，应明确保留 AST。

func buildWithMode(fset *token.FileSet, files []*ast.File) (*doc.Package, error) {
	// AllDecls 展示未导出声明；PreserveAST 留给后续分析继续使用。
	mode := doc.AllDecls | doc.PreserveAST
	return doc.NewFromFiles(fset, files, "example.com/project/widget", mode)
}

实际选择可以按下面三层判断：只做公开文档就使用默认模式；做源码索引或内部 API 浏览再考虑 AllDecls；同一份 AST 还要交给静态分析器时，再增加 PreserveAST。不要把 Mode 当成构建标签过滤器，两者解决的是不同问题。

常见问题

只传一个源码文件也能生成包文档吗？

可以返回文档对象，但它只反映传入文件。多文件包若想完整展示，必须先收集同一构建上下文下的全部目标文件。

为什么文档里没有 Example？

先确认对应的 _test.go 是否进入文件切片，再检查示例函数名是否符合 ExampleFoo 或带后缀的命名约定。

什么时候应该传 PreserveAST？

当后续流程还要读取 AST 节点、函数体或位置信息时传入；只渲染文档且不再使用 AST 时，可以按内存需求选择默认行为。