== Some notes on Go's godoc and what it formats how I spent part of today banging my head against [[Go http://golang.org/]]'s [[godoc tool http://godoc.org/code.google.com/p/go.tools/cmd/godoc]], so here are some notes about what it formats how. In general godoc is frustratingly under-documented and the available documentation is scattered around hither and yon. As lots of things will tell you, you write documentation for an entire package by putting a comment block at the start of one file in the package. Like other documentation comments, this comment must end *right before* the _package_ line. If you accidentally leave a blank line between the end of your documentation comment and the _package_ line, _godoc_ will silently ignore your comment. Speaking from personal experience, this can be very puzzling and frustrating if you don't realize what's going on. (This is handy behavior if you want to add explanatory internal use comments in some of your source files; just put a blank line between the comments and the _package_ line and godoc will skip them all.) In its HTML rendition of your package or command documentation, godoc will turn some lines into headings (and in some versions of godoc you then get an index to them at the top of the page). As [[what documentation there is notes http://golang.org/pkg/go/doc/#ToHTML]], this is: > [...] a span that consists of a single line, is followed by another > paragraph span, begins with a capital letter, and contains no > punctuation is formatted as a heading. That a heading must be followed by another regular paragraph span means that you can't put a heading immediately before an indented section that is a preformatted block. For example, if you're describing command options you can't have an 'Options' heading immediately before a preformatted block covering all of the options. You need to shim in some sort of sentence or remark. Godoc rendering plain text will indent your indented sections somewhat further than you did in the original comment, especially if you used ((/* ... */)) to write a big section of what is basically plain text (this seems to be a common approach for large multi-line blocks of package or command documentation). Word-wrap your indented sections with generous right margins to compensate for this. Godoc appears to sometimes do odd things if more than one file in a package has what godoc considers to be package level comments; when I did this by accident I got a confusing jumble of text that was not what I expected. So I think the rule here is 'don't even think about doing that' (which is what [[Godoc: documenting Go code http://blog.golang.org/godoc-documenting-go-code]] says to do). Sadly it's easy (for me) to have accidents where you have a big block of internal explanation comments at the start of a file and then forget to leave a blank line between them and the _package_ line. I agree with the [[recommended http://blog.golang.org/godoc-documenting-go-code]] approach of putting all your Godoc documentation in a separate _doc.go_ file once it gets large enough. I'm using ((/* ... */)) and basically treating it as a plain text file. === Sidebar: Additional trivia Based on how Godoc behaves on the standard packages, it will ignore at least some copyright declaration blocks at the top of your file. The [[doc package variables http://golang.org/pkg/go/doc/#pkg-variables]] suggest that this might be relatively generic but it's clearly undocumented so I'm not sure counting on this is wise. If I needed to have copyright notices I'd put them in a comment below the _package_ line. See for example [[the _go vet_ doc.go file https://code.google.com/p/go/source/browse/cmd/vet/doc.go?repo=tools]] for an example of this.