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 <[email protected]> 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 <[email protected]> > 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 <[email protected]> > > Juju Core Sapphire Team <http://jujucharms.com> > > > > -- > > Juju-dev mailing list > > [email protected] > > Modify settings or unsubscribe at: > > https://lists.ubuntu.com/mailman/listinfo/juju-dev > > > > -- > Juju-dev mailing list > [email protected] > Modify settings or unsubscribe at: > https://lists.ubuntu.com/mailman/listinfo/juju-dev >
-- Juju-dev mailing list [email protected] Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/juju-dev
