Skip to content
Tutorials Center
My learning

Topics

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.

Terminal
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.

Go Extracting doc comments the way go doc does

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.

Go Doc comment syntax: headings, lists and code

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

Terminal
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 the package line, in one file per package (often doc.go).
  • Formatting in comments (Go 1.19+): a # line is a heading; indented lines are code; lines starting with -, * or 1. form lists; [Name] and [pkg.Name] become links; bare URLs are linked. gofmt normalizes 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 ExampleParse in _test.go files show up with the symbol and are checked by go test if they have an // Output: comment.
  • Directives are not docs. Lines like //go:generate or //go:build directly above a declaration are skipped from the printed text.
  • Offline and fast. go doc reads the source, so it shows what is on your machine, matching your module versions. It needs the dependency in the module cache: run go mod download if 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 doc exits with status 1 and prints no symbol ... in package ...; use go doc -short pkg to see the available names.