Go Reference ยท The go Command and Tools
The go doc command
Reference for go doc: show package, function, type and method documentation from the terminal, flags -all -src -u -short -c, and how doc comments are written.
go doc prints documentation for a package, a constant, a variable, a function, a type, or a method, taken from the doc comments in the source. It works offline and for your own code as well as the standard library, so you can look something up without leaving the terminal. The same comments power pkg.go.dev and editor hover text.
The command is forgiving about how you name things: go doc strings.Builder, go doc strings Builder and go doc strings.builder (case-insensitive when there is no capital letter in the query) all work. With no argument it documents the package in the current directory.
go doc fmt # package summary go doc fmt.Printf # one function go doc strings.Builder.Grow # a method go doc -all sort # the complete documentation of a package go doc -src errors.New # the source of one symbol
Try it
Doc comments are just comments attached to declarations. The go/parser and go/doc packages extract them, which is how go doc works internally.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.
Syntax
go doc [flags] [package|[package.]symbol[.methodOrField]]
go doc [flags] [package] [symbol[.methodOrField]]
| Flag | Description |
|---|---|
-all |
Show all documentation for the package: every exported symbol, with its comments. |
-short |
One line per symbol. |
-src |
Print the full source of the symbol, not just its declaration. |
-u |
Include unexported symbols and their docs. |
-c |
Match symbol names case-sensitively (default is insensitive when your query is lowercase). |
-cmd |
Treat a main package as a normal package and show its exported symbols. |
Lookup rules: a single word is a package if one matches, otherwise a symbol in the current package. go doc json.Decoder finds encoding/json because it matches a unique path suffix. When several packages match, go doc picks one by its search order (your module first, then the standard library, then dependencies), so write a longer path such as encoding/json when you need a particular one.
Usage notes
- Writing doc comments. A doc comment is the comment block directly above a declaration, with no blank line between. It should start with the name it describes:
// Parse reads .... The package comment goes above thepackageline, in one file per package (oftendoc.go). - Formatting in comments (Go 1.19+): a
#line is a heading; indented lines are code; lines starting with-,*or1.form lists;[Name]and[pkg.Name]become links; bare URLs are linked.gofmtnormalizes this layout, see go fmt. - Deprecation. A paragraph starting with
Deprecated:marks a symbol as deprecated; editors and linters show warnings, and pkg.go.dev groups them separately. - Examples are documentation. Functions named
ExampleParsein_test.gofiles show up with the symbol and are checked by go test if they have an// Output:comment. - Directives are not docs. Lines like
//go:generateor//go:builddirectly above a declaration are skipped from the printed text. - Offline and fast.
go docreads the source, so it shows what is on your machine, matching your module versions. It needs the dependency in the module cache: rungo mod downloadif a package is missing. - Browsing the web version.
pkgsite(golang.org/x/pkgsite/cmd/pkgsite) serves the same documentation locally as a website, including your own modules. - No match.
go docexits with status 1 and printsno symbol ... in package ...; usego doc -short pkgto see the available names.