Description
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 // Package xxx ...
syntax. This will follow the current godoc rules and allow for code blocks, etc.:
// 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 -m
flag to put go doc
in module mode, much like go list -m
vs go list
. This will only accept module import paths not packages, again like go list
, and will display the module doc string, and full package listing.
$ 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?
README
The forthcoming discovery service, #33654, currently uses the repo's README for top level documentation, since this is a fairly strong pseudo-convention for most repos. Unfortunately, while this works well for a web ui, this syntax may not be as readable on the command line, or format well with godoc.
versions
It may be useful to list all known versions, but this implies that the list is up to date, and I would rather not impose a full go get
flow. This could be gated behind -all
or a new flag.
packages
noise
For complex packages, say k8s.io/kubernetes
, listing all the packages may be really noisy. As such it may be useful to gate this data behind -all
. That being said many protobuf generated packages suffer from the same noise.
stutter
The current syntax also suffers from stutter, because all package lines start package xxx // import ...
. This format borrows from the package declaration syntax to be more legible to readers. It also feels like the type declarations that can be found in regular godoc:
package unix // import "internal/syscall/unix"
const AT_REMOVEDIR = 0x200
const AT_SYMLINK_NOFOLLOW = 0x100
submodules
While they are not contained within the module, many customers may be confused about why they cannot find the cloud.google.com/go/datastore
package within the cloud.google.com/go
module. This could be displayed like so, in addition to being guarded behind -all
or a custom flag:
module cloud.google.com/go
package cloud // import "cloud.google.com/go"
package asset // import "cloud.google.com/go/asset/apiv1"
...
module cloud.google.com/go/bigquery
module cloud.google.com/go/bigtable
...
Metadata
Metadata
Assignees
Type
Projects
Status