Go takes its documentation very seriously, and nobody would blame you if you found it confusing that someone might reference
godoc in one breath and
go doc in the next.
This isn’t just a to-may-to to-mah-to kind of thing. All of these concepts are related.
godoc—the web server
godoc tool is intended primarily to run a documentation server in your browser on localhost.
It includes the documentation for the Go standard library, along with any package that lives in your GOPATH.
It can also format documentation as plain text on the command-line, where you would pass the import path of the package you are interested in. This was added as an afterthought.
godoc without any arguments will output the usage statement for the tool.
usage: godoc package [name ...] godoc -http=:6060 ...
go doc—the go subcommand
go command-line tool, which is used to
go run or
go build or
go test, also has a subcommand
doc subcommand will print out the documentation for whatever argument you pass it: a package, const, func, type, var, or method.
go doc was intended from the start to be convenient from the command-line.
The most important difference between
go doc on the command-line, is that the syntax for
go doc is, well, Go.
go doc gob.Decoder
The equivalent command using
godoc is a bit more awkward, requiring the full import path:
godoc encoding/gob Decoder
The default behavior of
go doc when calling it without arguments, is to display the documentation for the current package.
godoc.org is, confusingly, sometimes referred to as GoDoc. It hosts documentation for Go packages that are not a part of the Go standard library. Anything hosted publicly on Bitbucket, GitHub, Google Project Hosting or Launchpad is likely to show up on GoDoc. In fact, searching for a project by its import path will automatically add it to the site.
The documentation that you will see on godoc.org is very similar to the documentation that you get when running the local
godoc server, but as pointed out in the comments, godoc.org doesn’t use the output from the
godoc and the website godoc.org both rely on the package
go/doc to extract source code documentation.
If you were to use
godoc to ask about
go/doc, it would tell you all about it.
$ godoc go/doc PACKAGE DOCUMENTATION package doc import "go/doc" Package doc extracts source code documentation from a Go AST. ...
If in doubt…
When people are referring to the package go/doc in casual conversation, they’ll often drop the slash. And when saying go doc they could be referring to GoDoc, the website. And, you know how it is… they might actually be talking about the godoc tool.
If you’re unsure of exactly which one they mean, ask for clarification!
go/doc is used by other tools to extract the documentation comments from the AST.
The command-line tool
godoc is a web server first, and outputs plain text documentation to STDOUT as an afterthought, whereas
go doc is intended to be used to output documentation on the command-line.
The godoc.org website is the publicly searchable documentation for go packages that are not a part of the standard library.
With thanks to Rob Pike for clarifying the reasoning behind the various tools.