<div dir="ltr"><div><div>Absolutely, Roger. This maintenance aspect is one of the very important values of a proper documentation.<br><br></div>@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. ;)<br><br></div>mue<br><br></div><br><div class="gmail_quote"><div dir="ltr">On Thu, Aug 27, 2015 at 9:51 AM roger peppe <<a href="mailto:roger.peppe@canonical.com">roger.peppe@canonical.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">On 27 August 2015 at 08:39, James Tunnicliffe<br>
<<a href="mailto:james.tunnicliffe@canonical.com" target="_blank">james.tunnicliffe@canonical.com</a>> wrote:<br>
> A good way of reading go docs is "godoc -http=:6060" and pointing your<br>
> browser at <a href="http://localhost:6060/pkg/github.com/juju/juju/" rel="noreferrer" target="_blank">http://localhost:6060/pkg/github.com/juju/juju/</a> to read the docs<br>
> - no grep required.<br>
<br>
+1.<br>
<br>
Or "godoc ." if you're in the package directory.<br>
Or <a href="http://godoc.org/github.com/juju/juju" rel="noreferrer" target="_blank">http://godoc.org/github.com/juju/juju</a>.<br>
<br>
Having proper package docs is lots better than using README.md<br>
files - it fits into the Go ecosystem. The godoc is always the first<br>
thing I look at when trying to understand a package - it's nicely indexed<br>
with pointers to all the relevant source code entry points. Having<br>
a decent package doc is important.<br>
<br>
In my view, it's important not just for explaining to people how<br>
to use the package, but also for people maintaining the package,<br>
so that the motivations and concerns of the package are laid out<br>
clearly, helpful for avoiding feature creep and code sprawl.<br>
<br>
  cheers,<br>
    rog.<br>
<br>
--<br>
Juju-dev mailing list<br>
<a href="mailto:Juju-dev@lists.ubuntu.com" target="_blank">Juju-dev@lists.ubuntu.com</a><br>
Modify settings or unsubscribe at: <a href="https://lists.ubuntu.com/mailman/listinfo/juju-dev" rel="noreferrer" target="_blank">https://lists.ubuntu.com/mailman/listinfo/juju-dev</a><br>
</blockquote></div><div dir="ltr">-- <br></div><div dir="ltr">Frank Mueller <frank.mueller<a>@canonical.com</a>><br>
Juju Core Sapphire Team <<a>http://jujucharms.com</a>></div>