go doc & pkg.go.dev — documentation

Overview

Go documentation is plain comments, no markup language: a comment directly above a declaration is its doc. go doc renders them in the terminal, and pkg.go.dev renders them for every public module automatically — the ecosystem's javadoc, with zero publishing step.

Key points

• go doc: go doc fmt.Println, go doc -all net/http, go doc -src json.Marshal — works on the stdlib, the current module, and anything in the module cache.
• Comment conventions: start with the identifier's name ("Println formats…"); since Go 1.19 doc comments support links, lists, and headings (gofmt reformats them).
• Deprecation: a paragraph starting Deprecated: is the machine-readable notice — staticcheck (SA1019) and pkg.go.dev both surface it; there is no annotation syntax.
• Examples are tests: func ExampleXxx() in a _test.go file with an // Output: comment is compiled and run by go test — examples cannot rot.
• Runnable in docs: pkg.go.dev renders ExampleXxx functions as editable, runnable snippets in the package page; suffix forms (ExampleFoo_bar) attach to methods.
• pkg.go.dev: indexes every fetched public module version via the module proxy; shows docs, licence, imports/imported-by, and vulnerability notices — nothing to upload.
• Local server: pkgsite (golang.org/x/pkgsite/cmd/pkgsite) serves the same rendering locally for private modules; the old godoc server is retired.

Examples

// Package cache implements a fixed-size LRU cache.
//
// Deprecated: use container/lru instead.
package cache

func ExampleCache_Get() {
    c := New(2)
    c.Put("k", 1)
    fmt.Println(c.Get("k"))
    // Output: 1 true
}

Related

• The go command & tool catalog — parent catalog of the toolchain.
• go test — runs Example functions as part of the test suite.
• javadoc — the JVM counterpart: a markup language and an explicit publishing step, where Go ships plain comments and a central site.