Proposal: doc.go for each package

[roger peppe]

+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
>