Wandering Thoughts archives

Some notes on Go's godoc and what it formats how

I spent part of today banging my head against Go's godoc tool, 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, 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 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 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 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 for an example of this.