<div dir="ltr">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.<div>
<br></div><div>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.</div>
<div><br></div><div>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</div>
<div><br></div><div>If you need help writing godoc, or just want a refresher, please read through my godoc tutorial: <a href="https://godoc.org/github.com/natefinch/godocgo">https://godoc.org/github.com/natefinch/godocgo</a></div>
<div><br></div><div>-Nate<br></div></div>