给定一个如下的包布局：

.
└── pkg
    └── pkg1
        ├── a.go
        ├── b.go
        └── pkg1.go

可以为出现在文档概览中的包声明编写文档。

但我该如何对文档进行排序？

如果我在 pkg1.go 中执行如下操作

// Package pkg1
// does something...
package pkg1

而且信息仅出现在pkg1中，那么它将在概览中排在前面。

如果我随后在 a.go 中再添加一些内容，那么该信息将会排在第一位。

假如在 pkg1.go 中添加文档，是否更符合惯例，前提是我确实有一个？还是也许创建一个空的 0.go，它将始终首先出现，且在文档中便于浏览并理解其行为？

解决方案

你不能可靠地控制跨多个文件的包文档顺序。虽然它看起来像按照文件顺序，但这种行为并不能得到保证。

地道的做法是在一个地方定义包注释（通常是 doc.go），并避免在其他文件中重复它。

根据Go文档中的一段注释（go.dev/doc/comment）

对于多文件包，包注释应仅出现在一个源文件中。如果多个文件有包注释，它们会被拼接成整个包的一个大型注释。