Proposal: doc.go for each package

[James Tunnicliffe]

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.

James



On Wed, Aug 26, 2015 at 6:17 PM, roger peppe <roger.peppe at canonical.com>
wrote:

> +1.
>
> We should definitely have package docs for every package,
> explaining what it's for, how it is intended to be used and explaining
> any overarching concepts.
>
> There's no particular need for it to be in a separate doc.go file
> though.
>
> On 26 August 2015 at 14:11, Frank Mueller <frank.mueller at canonical.com>
> wrote:
> > Hi,
> >
> > I would like to share an idea with you.
> >
> > As our codebase gets larger and larger the chance of touching areas
> you've
> > never worked before gets larger too. So you often need some time to get
> > behind the concepts here. So for example many testing packages we have
> > follow different ideas. Some only contain small helpers, others larger
> stub
> > environments as a test bed allowing to inject errors and trace calls. And
> > that's only testing. ;)
> >
> > So my proposal is to establish the writing of a doc.go for each package
> > containing a high-level description (details have to be as usual at the
> > accodring code parts) of the intention and usage of the package. This
> file
> > only contains our copyright, this documentation, and the package
> statement.
> >
> > // Copyright 2015 Canonical Ltd.
> > // Licensed under the AGPLv3, see LICENCE file for details.
> >
> > // Package foo is intended to provide access to the foo
> > // cloud provider. Here it ...
> > package foo
> >
> > This way we not only provide a good documentation for sites like
> godoc.org
> > but also for ourselves when walking through the code. It's a fixed anchor
> > for an initial orientation without searching. Sure, often this is
> already in
> > or could be done into the major package files, like here in the example a
> > foo.go. But having a fixed name for the doc containing file makes it more
> > simple to navigate to, a recursive grep through all doc files is pretty
> > simple, and last but not least it's more obvious if this documentation is
> > missing (existance check could be part of CI, sadly not a quality check
> > *smile*).
> >
> > So, what do you think?
> >
> > mue
> >
> > --
> > Frank Mueller <frank.mueller at canonical.com>
> > Juju Core Sapphire Team <http://jujucharms.com>
> >
> > --
> > Juju-dev mailing list
> > Juju-dev at lists.ubuntu.com
> > Modify settings or unsubscribe at:
> > https://lists.ubuntu.com/mailman/listinfo/juju-dev
> >
>
> --
> Juju-dev mailing list
> Juju-dev at lists.ubuntu.com
> Modify settings or unsubscribe at:
> https://lists.ubuntu.com/mailman/listinfo/juju-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/juju-dev/attachments/20150827/74ddc984/attachment-0001.html>