Go 中如何控制包文档的显示顺序？

2026-11-04数据小许

建议将整个包的文档注释集中写在一个文件中。可以使用已有的 pkg1.go；如果文档较长，或希望文档入口更容易找到，用 doc.go 更合适。无需为了排序创建 0.go。

标准库 go/doc 的实现会先按文件名排序，再读取各文件。遇到多个包文档注释时，它会依次拼接这些注释。因此，a.go 中的包文档会出现在 pkg1.go 的包文档之前。这个顺序由文档提取工具的实现决定，与文件的创建或修改时间无关。go/doc 源码

多个文件中的包文档会合并，但仅在 a.go 中添加函数、类型或普通注释，并不会让它们自动成为包概览。Go 的文档指南建议，多文件包只在一个源文件中保留包文档注释。Go Doc Comments

两种方式都可以，根据文档的规模和组织需要选择：

如果包说明较短，且 pkg1.go 适合作为主要文件，可以直接写在其中。
如果包说明较长，或需要介绍整体用法，可以集中写在 doc.go。这个文件可以只包含包文档注释和 package 声明，这也是 Go 项目中已有的文档惯例。Go 官方文档介绍

doc.go 这个文件名本身不会获得特殊的排序优先级。集中保留一份包文档后，就不需要通过文件名控制不同文档片段的顺序。

例如，doc.go 可以写成：

// Package pkg1 does something.
//
// 在这里补充包的整体说明，并按阅读顺序组织各段内容。
package pkg1

包文档注释应紧贴 package pkg1，中间不要插入空白行；需要分段时，使用示例中的空注释行 //。Go Doc Comments

整理后，在 pkg1 所在目录运行：

go doc

检查包说明是否完整、段落顺序是否符合预期。如果最终发布到其他文档平台，还应查看该平台的实际渲染结果。

在上述按文件名排序的实现中，0.go 会排在示例中的其他文件之前，但这仍然依靠文件名安排内容。以后添加其他包文档时，还需要维护它们之间的顺序。

此外，完全空白的 0.go 无法承载包文档；作为 Go 源文件，它仍需包含 package pkg1 声明。使用常见的 doc.go 命名并集中维护包说明，更容易让维护者找到文档入口。