Great idea, I'll do it
On Thu, Aug 21, 2014 at 5:52 PM, Nate Finch <[email protected]> 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 > [email protected] > Modify settings or unsubscribe at: > https://lists.ubuntu.com/mailman/listinfo/juju-dev > >
-- Juju-dev mailing list [email protected] Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/juju-dev
