Proposal: doc.go for each package

[roger peppe]

On 27 August 2015 at 08:39, James Tunnicliffe
<james.tunnicliffe at canonical.com> wrote:
> A good way of reading go docs is "godoc -http=:6060" and pointing your
> browser at http://localhost:6060/pkg/github.com/juju/juju/ to read the docs
> - no grep required.

+1.

Or "godoc ." if you're in the package directory.
Or http://godoc.org/github.com/juju/juju.

Having proper package docs is lots better than using README.md
files - it fits into the Go ecosystem. The godoc is always the first
thing I look at when trying to understand a package - it's nicely indexed
with pointers to all the relevant source code entry points. Having
a decent package doc is important.

In my view, it's important not just for explaining to people how
to use the package, but also for people maintaining the package,
so that the motivations and concerns of the package are laid out
clearly, helpful for avoiding feature creep and code sprawl.

  cheers,
    rog.