2014-06-19
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.