gogetdoc
Retrieve documentation for items in Go source code.
Go has a variety of tools that make it easy to lookup documentation.
There's the godoc HTTP server, the go doc command line tool, and https://godoc.org.
These tools are great, but in many cases one may find it valuable to lookup
documentation right from their editor. The problem with all of these tools
is that they are all meant to be used by a person who knows what they are
looking for. This makes editor integration difficult, as there isn't an easy way
to say "get me the documentation for this item here."
The gogetdoc tool aims to make it easier for editors to provide access to
Go documentation. Simply give it a filename and offset within the file and
it will figure out what you're referring to and find the documentation
for it.
Usage
Simply specify a filename and byte offset with the pos flag:
$ gogetdoc -pos "$(go env GOROOT)/src/fmt/format.go:#2351"
import "unicode/utf8"
func RuneCountInString(s string) (n int)
RuneCountInString is like RuneCount but its input is a string.
The -json flag can be used to enable the extended JSON output.
In this mode, a JSON object will be written to stdout instead of the raw doc.
{
"name": "RuneCountInString",
"import": "unicode/utf8",
"pkg": "utf8",
"decl": "func RuneCountInString(s string) (n int)",
"doc": "RuneCountInString is like RuneCount but its input is a string.\n",
"pos": "/usr/local/Cellar/go/1.9/libexec/src/unicode/utf8/utf8.go:412:6"
}
Unsaved files
gogetdoc supports the same archive format as guru (formerly oracle).
Editors can supply gogetdoc with the contents of unsaved buffers by
using the -modified flag and writing an archive to stdin.
Files in the archive will be preferred over those on disk.
Each archive entry consists of:
- the file name, followed by a newline
- the (decimal) file size, followed by a newline
- the contents of the file
Editor Support
The following editor plugins are known to support gogetdoc:
- Atom: go-plus https://github.com/joefitzgerald/go-plus
- VS Code: vscode-go https://github.com/Microsoft/vscode-go
- Vim: vim-go https://github.com/fatih/vim-go
- Emacs: go-mode https://github.com/dominikh/go-mode.el
Contributions
Are more than welcome! For small changes feel free to open a pull request.
For larger changes or major features please open an issue to discuss.
Credits
The following resources served as both inspiration for starting this tool
and help coming up with the implementation.
- Alan Donovan's GothamGo talk "Using
go/typesfor Code Comprehension
and Refactoring Tools" https://youtu.be/p_cz7AxVdfg - Fatih Arslan's talk at dotGo 2015 "Tools for working with Go Code"
- The
go/typesexample repository: https://github.com/golang/example/tree/master/gotypes
License
gogetdoc is licensed under the 3-Clause BSD license - see the LICENSE file for details.
Portions of this code are borrowed from the Go project and are Copyright 2015 The Go Authors.