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: cmd/doc: module documentation #35544
What did you see today?
Currently there is no place to put module level documentation that is consumable via the toolchain.
What would you like to see?
We should standardise a doc string format that reads like the
// Module golang.org/x/sys provides OS specific interfaces for low level operations. // // ... module golang.org/x/sys go 1.13
We should add a new
$ go doc -m golang.org/x/sys module golang.org/x/sys Module golang.org/x/sys provides OS specific interfaces for low level operations. ... package cpu // import "golang.org/x/sys/cpu" package plan9 // import "golang.org/x/sys/plan9" package unix // import "golang.org/x/sys/unix" package main // import "golang.org/x/sys/unix/linux" package windows // import "golang.org/x/sys/windows" package main // import "golang.org/x/sys/windows/mkwinsyscall" package svc // import "golang.org/x/sys/windows/svc" package debug // import "golang.org/x/sys/windows/svc/debug" package eventlog // import "golang.org/x/sys/windows/svc/eventlog" package main // import "golang.org/x/sys/windows/svc/example" package mgr // import "golang.org/x/sys/windows/svc/mgr" package registry // import "golang.org/x/sys/windows/svc/registry"
What alternatives did you consider?
Thanks for making this proposal.
I have considered this problem space in the past and wrote a proposal draft related to "module comments", but upon review and thinking more about it, I've realized there were reasons not to propose the change at that time.
There may be useful and relevant information in my proposal draft, so I've posted it so that it is available for reading. See issue #35546.
I created this proposal to resolve a question I had from the new pkg.go.dev site:
I felt like for a web ui, use of
Currently package docs frequently do both, especially at the repo root. With this, a package would document how the exported symbols are to be used, which ones are important, maybe some code samples, and relationships with other packages. E.g.
A module should document why you should use the features within. It should describe what it was built to do, call out important packages and note shared features/concern between packages. E.g.
This works better for complex libraries that have many packages, like
The other feature is the ability to list out the packages in a module. There may be a way to do this with
Go programs import packages. It makes sense to ask for the documentation for a package.
It is a mistake to place emphasis on the module. Focus on the package. Especially for a single-package module, the documentation has always been on the package and it should remain there. A large module like cloud.google.com/go may benefit from a brief overview in a README, and that seems fine.
I'm reluctant to formalize module documentation any more than that.
My goal is to standardize a location to document why they are versioned together, and interface(s) to consume this data. This is frequently information that I want to extract from a module, without cloning or poking around in
What is your view on empty
pkg.go.dev is formalizing this, and in a way that is not very compatible with CLI tools. Is the path that the language would like to take? I am a very large fan of