Original post

has a great, well documented standard library. You may find yourself spending
a fairly significant chunk of your Go time digging in stdlib docs,
which is reasonable to expect at least for novice Go coders.

How do folks look for stuff in the docs? There are several ways. You can just
use Google, which indexes the docs very well. It’s fairly time consuming,
though. devdocs.io is wonderful, and it’s auto-complete
function is a real time saver.

But what if you want to stay within the terminal when searching documentation?

Luckily, Go comes with its own private take on mango doc [1]. So you
can just type:

$ go doc regexp.Split
func (re *Regexp) Split(s string, n int) []string
    Split slices s into substrings separated by the expression and returns a
    slice of the substrings between those expression matches.
    [...]

Which is pretty good, with one significant problem. You have to provide the
function/type name exactly, including its package. If you don’t remember it
exactly, that’s a problem. Even if you do, it may be fairly long to type in;
consider go doc encoding/csv.Reader.ReadAll – that’s quite a handful!

I wouldn’t be a hacker at heart if I wasn’t willing to spend a few hours
automating a task that takes 3 extra seconds. So I hacked up together an
“autocompletion engine” for go doc. Here’s an animated GIF showing it in
action:

Animated GIF showing autocomplete for go doc

The full code is here. Here’s an
overview of what’s going on.

The main tool is index-doc.go, which takes a path to the Go source directory
(which is installed with Go), then goes over all the files found there,
extracting the full symbol path of every function, type and variable. Don’t
panic – Go has a bunch of Go-processing tools built into the standard library,
so there’s no need to manually parse Go code here. The packages go/parser,
go/build and go/doc are doing all the heavy lifting [2].

It then dumps a list of these symbols onto stdout, which can be piped into
a file.

Next, comes one of my favoring Linux command-line tools – dmenu. The file with the symbols is piped into
it using a Bash function:

gdoc() {
    cat $HOME/.gosyms | dmenu -l 20 -i -b -p "go doc" | xargs go doc
}

dmenu handles the fuzzy search and autocompletion, and passes the selected
result into go doc that displays the documentation. That’s it!

Now I can conveniently find all I need in Go’s docs without even leaving the
terminal, and without remembering package paths and symbol names exactly.
Auto-completion works really well for tasks like “wait, what was that function
that creates temporary files?” — just start typing tempf into the menu
gdoc pops up and immediately find io/ioutil.TempFile. The tool can be
easily adjusted to index my own packages and installed 3rd party packages, as
long as they’re accessible from go doc.


[1] This page
provides a good overview of existing Go documentation tools.
[2] In fact, go doc itself uses the same packages.