Skip to content

proposal: cmd/doc: module documentation #35544

Open
@carnott-snap

Description

@carnott-snap

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

No one assigned

    Type

    No type

    Projects

    Status

    Hold

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions