Please Write Package Docs

[Matthew Williams]

Great idea, I'll do it


On Thu, Aug 21, 2014 at 5:52 PM, Nate Finch <nate.finch at canonical.com>
wrote:

> There's this great facility in Go where you can write a comment on the
> package <foo> declaration, and that comment will get used as top-level docs
> in godoc.  We should be using this, and (in general) we're not.
>
> This is a way to communicate why a package exists and what its code does
> in general terms.  This is useful to both help developers understand the
> code in the package, but also to help them understand whether new code
> should go into that package or somewhere else.  Good package docs can
> prevent our code from getting too spaghetti'd by having unrelated code in
> the same package.
>
> I suggest that all new packages should have package docs, and we should
> try to add package docs to existing packages when it's convenient.  If a
> package is only a single non-test file (and is very likely to stay that
> way), the package docs can just live in that single file.  If a package is
> multiple non-test files, and/or has a reasonable likelihood of being
> extended with more files, it's better to put the package docs in a
> canonical place so it's easy to find, which is traditionally a file called
> doc.go
>
> If you need help writing godoc, or just want a refresher, please read
> through my godoc tutorial: https://godoc.org/github.com/natefinch/godocgo
>
> -Nate
>
> --
> Juju-dev mailing list
> Juju-dev at lists.ubuntu.com
> Modify settings or unsubscribe at:
> https://lists.ubuntu.com/mailman/listinfo/juju-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/juju-dev/attachments/20140821/2243b2e2/attachment.html>