ARTICLE AD BOX
Given a package layout as follows:
. └── pkg └── pkg1 ├── a.go ├── b.go └── pkg1.goIt's possible to write documentation for the package declaration that appears in the docs overview.
But how do I order the documentation?
If I do the following in pkg1.go
// Package pkg1 // does something... package pkg1And the info only appears in pkg1, then it will appear first in the overview.
If I subsequently add something to a.go then that info will appear first.
Is it more idiomatic to add the documentation in pkg1.go assuming I have one? Or perhaps create a blank 0.go which will always appear first and is easy to browse as well as understand its behavior in the docs?
You can’t reliably control the order of package documentation across multiple files. While it may appear to follow file order, that behavior isn’t guaranteed.
The idiomatic approach is to define the package comment in a single place (usually doc.go) and avoid duplicating it in other files.
According to a comment from the Go docs (go.dev/doc/comment)
For multi-file packages, the package comment should only be in one source file. If multiple files have package comments, they are concatenated to form one large comment for the entire package.
2 Comments
That makes sense but do you have a reference to the part about doc.go?
2026-04-07T13:47:48.79Z+00:00
doc.go is a common convention where it only contains the package clause and its corresponding documentation comments most especially when you are writing a go package. However, it is not necessary you use doc.go, whichever file you choose, just ensure that only one file within a package should contain the package comments
2026-04-07T14:38:59.567Z+00:00
Explore related questions
See similar questions with these tags.
