Proposal: doc.go for each package

[Frank Mueller]

Absolutely, Roger. This maintenance aspect is one of the very important
values of a proper documentation.

@James: Sure, for simple reading there are many existing ways. The little
grep idea is only to integrate more complex searches for information into
my editor. Naming it "grep" only has been too simple. ;)

mue


On Thu, Aug 27, 2015 at 9:51 AM roger peppe <roger.peppe at canonical.com>
wrote:

> 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.
>
> --
> Juju-dev mailing list
> Juju-dev at lists.ubuntu.com
> Modify settings or unsubscribe at:
> https://lists.ubuntu.com/mailman/listinfo/juju-dev
>
-- 
Frank Mueller <frank.mueller at canonical.com>
Juju Core Sapphire Team <http://jujucharms.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/juju-dev/attachments/20150827/c7312a7c/attachment.html>