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 <[email protected]> wrote: > On 27 August 2015 at 08:39, James Tunnicliffe > <[email protected]> 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 > [email protected] > Modify settings or unsubscribe at: > https://lists.ubuntu.com/mailman/listinfo/juju-dev > -- 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
