Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
proposal: define module comment convention for module documentation #35546
Note: This was a draft of a proposal that I decided against proposing at the time. I'm posting it at this time to share information and considerations relevant to this topic. See comment below for more information about why the proposal was ultimately not started.
There is no standard way to document Go modules. I propose defining the convention of a “module comment”, a comment immediately preceding the module statement in the go.mod file with semantics similar to that of a package comment, and using it for this purpose.
There is well-established convention for how to document a single Go package. It is done with package comments. A package comment is a comment preceding the package clause, with no blank line separating it. For example:
// Package bytes implements functions for the manipulation of byte slices. // It is analogous to the facilities of the strings package. package bytes
A package comment can be very detailed (for example, see
Go 1.11 has added preliminary support for Go modules. They are described as:
At this time, there is no standardized approach for documenting Go modules.
The go.mod file contains information at the module scope. It has a module statement. It allows line comments.
I propose following a pattern similar to package comments, and defining a “module comment” to be a comment preceding the module statement, with no blank line separating it. Here are a few simple examples of go.mod files with a module comment to illustrate the idea:
// Module sync provides Go concurrency primitives in addition to the ones // provided by the language and "sync" and "sync/atomic" packages. module golang.org/x/sync go 1.12
// Module text holds supplementary Go libraries for text processing, many involving Unicode. module golang.org/x/text require golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e
// Module tools holds various packages and tools // that support the Go programming language. // // Some of the tools, godoc and vet for example, // are included in binary Go distributions. // // Others, including the Go guru and the test // coverage tool, can be fetched with go get. // // Highlights of functionality provided: // // • a type-checker for Go // // • an implementation of the Static Single Assignment form (SSA) // representation for Go programs // module golang.org/x/tools go 1.11 require ( golang.org/x/net v0.0.0-20190620200207-3b0461eec859 golang.org/x/sync v0.0.0-20190423024810-112230192c58 golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7 )
The cleaned version of the first sentence of the module comment is the synopsis, which can be used in contexts where a short description is preferred. The synopsis of the tools module comment above is “Module tools holds various packages and tools that support the Go programming language.”
The entire module comment is the complete module documentation. It can be used in contexts where a detailed description is preferred, for example when viewing the module on a module discovery website (such as #33654). It would use the same semantics as Go package documentation, and the same rules could be used to render it into HTML form. This is documented and implemented in
See the following as an example of what very comprehensive module documentation can look like when rendered to HTML:
I am closing this issue because this is a proposal draft that I am withdrawing at the time; I don't actually propose we make this change now. It was posted to make information and relevant considerations available.
The main issue with this proposal turned out to be the problem it set out to solve, namely:
It became less clear what it meant to "document a module". A module can be thought of as a versioned delivery mechanism for Go packages. Go packages are documented, so it's not clear what is left to document at the scope of a module.
In order to revive this proposal, there needs to be an answer to the question of "why document a Go module."