Over a million developers have joined DZone.

Command-Line Autocomplete for Go Documentation

DZone's Guide to

Command-Line Autocomplete for Go Documentation

Need to lookup some Go documentation but don't want to leave the comfort of your terminal session? Then this post is for you. Read on to find out more.

· Integration Zone ·
Free Resource

Discover how you can get APIs and microservices to work at true enterprise scale.

Go has a great, well documented standard library. You may find yourself spending a fairly significant chunk of your Go programming 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 its 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 man - go 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.

This 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 isindex-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/parsergo/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.

APIs and microservices are maturing, quickly. Learn what it takes to manage modern APIs and microservices at enterprise scale.

go ,documentation ,command line ,integration

Published at DZone with permission of

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}