Repository: go
Issue: proposal: cmd/doc: module documentation
Labels: Documentation,Proposal,Proposal-Hold

### 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.:
```go
// 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.
```sh
$ 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:
```go
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:
```go
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
...
```