go-doc

View documentation for the current package

$ go doc

$ go doc [encoding/json]

$ go doc -all [encoding/json]

$ go doc -all -src [encoding/json]

$ go doc -all -src [encoding/json.Number]

go doc [flags] [package [symbol]]

-all
    Show documentation for all exported and unexported symbols. By default, only exported symbols are shown.

-cmd
    Treat main packages as commands, displaying their documentation. Useful for documenting command-line tools.

-short
    Display only the first sentence of the package documentation.

-src
    Show the actual Go source code alongside the documentation comments.

package
    The import path of the Go package to document (e.g., fmt, net/http).

symbol
    A specific identifier within a package (e.g., Println, File). Can be a function, type, variable, constant, or method. Used in conjunction with a package.

package.symbol
    A combined form to specify a symbol within a particular package directly (e.g., fmt.Println, os.File).

go doc is a powerful command-line utility provided as part of the Go toolchain. It allows developers to quickly access and display the documentation for Go packages, functions, types, variables, and constants directly from the terminal. The documentation is extracted from the Go source code itself, relying on well-formatted comments associated with declarations. This makes Go self-documenting to a high degree.

When invoked, go doc parses the specified Go package or symbol, renders its associated documentation comments, and prints them to standard output. It's an indispensable tool for understanding Go's standard library APIs, third-party libraries, and even one's own code without needing to consult external websites or IDEs. It can show detailed documentation for an entire package, or narrow down to a specific function or method within a package, making it highly versatile for quick lookups and API exploration.

Requires a functional Go installation and a properly configured Go environment (GOPATH or Go modules) to resolve package paths. The quality and completeness of the displayed documentation are entirely dependent on the comments present in the Go source code. go doc primarily focuses on documentation from source code; it does not fetch documentation from external web sources unless those are generated from the local source.

go doc leverages Go's module system (if enabled) or GOPATH to locate and resolve package import paths. This means it can find both standard library packages and third-party modules or local packages, provided they are correctly configured in your Go environment.

Historically, godoc referred to a standalone executable that could serve documentation via a web interface or print it to the console. With Go modules, the godoc web server functionality is now typically invoked via go doc -http or by installing golang.org/x/tools/cmd/godoc. go doc is the modern, integrated command-line tool within the main go binary for printing documentation to the terminal.

go doc has been an integral part of the Go programming language's standard toolchain since its early days. It emerged from the philosophy that Go code should be self-documenting, with rich comments directly embedded in the source files. The command was designed to provide developers with immediate, command-line access to this embedded documentation, complementing the godoc web server (which serves similar content over HTTP). Its development has closely tracked the evolution of the Go language itself, including adaptations for Go modules, ensuring it remains a relevant and essential utility for exploring Go APIs.

go(1), go help(1), godoc(1)