Please Write Package Docs

[Nate Finch]

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/juju-dev/attachments/20140821/8974f557/attachment.html>