Skip to content
Tutorials Center
My learning

Topics

Lesson 104 of 147 ยท Testing and Tooling

Documentation and Examples

Write Go documentation that tools understand - doc comment syntax, doc.go, runnable examples, go doc and pkg.go.dev, README and CHANGELOG habits, and how to keep an API stable across versions.

Code that nobody can understand is code that nobody can safely use. In Go, documentation is not an extra step done in a separate tool: it lives in the source as comments, a single tool reads it, and the same text appears in your editor, in the terminal and on the public website pkg.go.dev. If you write the comments in the right shape, you get all three for free.

The comments lesson introduced doc comments in a few lines. This lesson goes the rest of the way: the exact syntax (headings, lists, code blocks and links), how the tools turn comments into pages, how runnable examples work, what belongs in a README and a CHANGELOG, and how to evolve a public API without breaking the people who depend on it. Several programs below use the standard library's go/doc and go/doc/comment packages, the very code behind go doc, so you can see exactly how comments are interpreted.

What a doc comment is

A doc comment is a comment that sits directly above a top-level declaration (a package, constant, variable, function, type or method) with no blank line between them. Only exported names are shown by default. The rules of thumb:

  • Write complete sentences, and start with the name of the thing: // Slug returns ..., // A Reader reads .... Tools and search results show the first sentence as a summary, so it should make sense alone.
  • Say what it does and what the caller must know: units, edge cases, what happens on error, whether it is safe for concurrent use, whether the zero value is usable.
  • Do not repeat the signature in words. "Slug takes a string and returns a string" tells the reader nothing.
Go
// Slug returns a lowercase, dash-separated version of title that is safe
// to use in a URL. Letters and digits are kept; every other run of
// characters becomes a single dash. It returns "" if title has no letters
// or digits.
func Slug(title string) string {
	// ...
}

Package documentation starts with // Package name ... and sits above the package clause in any one file of the package. Programs (package main) are described with the name of the command: // Command gofind searches ... or // Gofind searches .... When the package comment is long, move it into its own file named doc.go that contains nothing but the comment and the package line:

Go
// Package slug converts titles and names into URL-friendly slugs.
//
// # Basic use
//
// Call [Make] with any string:
//
//	s := slug.Make("Hello, World!") // "hello-world"
//
// # Limits
//
// Slugs are cut at [MaxLen] bytes on a word boundary.
package slug

The doc comment syntax

Since Go 1.19 doc comments have a small, fixed syntax. It looks like Markdown but is simpler, and gofmt keeps it in canonical form. The elements:

Element How to write it
Paragraph Lines of text; a blank // line starts a new paragraph
Heading A line # Title with a blank line before and after
List Lines indented and starting with -, *, + or 1.; gofmt rewrites them to - item
Code block Lines indented by a tab (or spaces) after a blank line; shown in a monospace box
Doc link [Name], [Type.Method] or [pkg.Name] links to another declaration
URL link A bare https://... URL, or [Text] with a line [Text]: https://... at the end of the comment
Deprecation A paragraph starting with Deprecated:

Lines starting with //go: (such as //go:generate) are directives and are never shown in the documentation. There is no support for bold, italic or tables, on purpose: comments should be readable in the source as plain text.

The go/doc/comment package contains the real parser and printers. The program below feeds it a comment text and prints the plain-text, Markdown and HTML renderings:

Go How a doc comment is parsed and rendered

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.

The heading, the bullet list and the indented code block were recognized from plain text, and [strings.ToLower] became a link into another package. [Make] became a link because the program told the parser, through LookupSym, that Make exists; go doc and pkg.go.dev do this for you with the real list of names. In the HTML form you can see how the elements map to <h3>, <ul> and <pre>. A few details worth knowing:

  • A doc link to a name in the same package is written [Make]; for a method, [Reader.Read]; for another package, [strings.Builder] (the package must be imported by your file, or you write its full path [encoding/json.Marshal]).
  • A heading must be a single line, and its first character after # should be a capital letter in practice. It must be surrounded by blank lines, or it is just a line that starts with #.
  • The old heading style (a single capitalized line with no punctuation) was accepted before Go 1.19. Today you write # Heading, and gofmt converts the old form when it can.

gofmt formats doc comments too

Because the syntax is fixed, gofmt rewrites doc comments into the standard form: it indents lists, normalizes list markers, converts code-block indentation to a tab, and adds the blank lines headings need. Hand-written comments in older styles get tidied automatically:

Go gofmt normalizes a doc comment

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.

The two indented * lines became a proper list (// - lowercase only), and the code line became a tab-indented block. Note that list items must be indented: an unindented * item is plain text. The gofmt output is the shape you should write by hand from the start.

From comments to documentation: go/doc

To produce documentation a tool must find the doc comments and attach them to the right declarations. The go/doc package does this, and you can use it yourself. The program below parses a small package and a test file held in strings, then prints a miniature version of what go doc shows: the package synopsis, constants, functions (flagging deprecated ones), types with their methods, and the examples:

Go A tiny go doc built with go/doc

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.

Notice that helper is missing, because it is unexported; that the constructor New is listed under the type Maker; and that the deprecation marker is found simply by looking for a paragraph that starts with Deprecated:. Editors, linters and staticcheck use that same convention to warn callers (go vet and linting).

Deprecation

When an API should no longer be used, keep it working, and add a paragraph that begins with Deprecated: followed by what to use instead:

Go
// ParseConfig reads a configuration file.
//
// Deprecated: Use [Load], which also supports environment overrides.
func ParseConfig(path string) (*Config, error) { return Load(path) }

Do not remove it right away. Within a major version a deprecated function stays, because removing it would break callers (more on that below).

go doc: documentation in the terminal

The go doc command prints documentation from the source on your machine, including your own packages and your dependencies. Because it reads the doc comments directly, it is always in step with the code:

Terminal
go doc strings             # package overview: synopsis and the list of exported names
go doc strings.Builder     # one type, with its methods
go doc strings.Builder.Grow
go doc -all strings        # everything, in full
go doc -src strings.Fields # print the source of a function
go doc -u mypkg            # include unexported names
go doc encoding/json Marshal

Typical output for a function looks like this:

TEXT
$ go doc strings.Fields
package strings // import "strings"

func Fields(s string) []string
    Fields splits the string s around each instance of one or more consecutive
    white space characters, as defined by unicode.IsSpace, returning a slice of
    substrings of s or an empty slice if s contains only white space.

Your editor shows the same text when you hover over a name. This is why the first sentence matters so much: it is what people read when they decide whether a function does what they need.

Examples: documentation that is tested

An example is a function named Example... in a _test.go file. If its last comment begins with // Output:, go test runs it and compares the printed text (benchmarks and fuzzing shows this running). On pkg.go.dev the code appears under the thing it documents with a Run button, so users can see and try real usage that is guaranteed to compile. The function name decides where it is shown:

Function name Documents
func Example() The package as a whole
func ExampleMake() The function Make
func ExampleMaker() The type Maker
func ExampleMaker_Make() The method Maker.Make
func ExampleMake_empty() A second example for Make, called "empty". The suffix after _ must start with a lowercase letter
func Example_pipeline() A package-level example named "pipeline"

Put examples in the external test package (package slug_test) so they use your package the way a user would, through its exported names and with an import. If an example has no // Output: comment, it is compiled but not run, which is the right choice for code that needs a network or a database.

Keep examples short and focused on one idea. Good documentation shows the common case first and lets people discover the rest.

README, CHANGELOG and the website

Doc comments describe the API. A project also needs documents that describe the whole:

  • README.md is the front door, and it should answer five questions quickly: what is this, how do I install it (go get example.com/slug@latest), what is the smallest working example, where is the full documentation (a link to pkg.go.dev), and what is the license. Add badges and long tutorials only after those basics. A reader should know within thirty seconds whether the project is what they need.
  • CHANGELOG.md lists what changed in each release, newest first, grouped as Added, Changed, Deprecated, Removed, Fixed and Security. It is written for humans (not a dump of commit messages) and it always says if a change can break callers. The popular "Keep a Changelog" format is a good template.
  • LICENSE: pkg.go.dev only displays documentation for modules that have a recognized open-source license file.
  • CONTRIBUTING.md and SECURITY.md are optional but helpful: how to run the tests and how to report a vulnerability.

pkg.go.dev

The website pkg.go.dev generates documentation for every public module automatically. You do not upload anything: it fetches versions from the Go module proxy, parses the doc comments with the code you just saw, and renders the package page, with the examples, the list of versions, the imports and the importers, and the license information. A new tagged version appears after someone requests it (go get example.com/[email protected]) or when you press "Request" on the site. It only shows tagged versions and the newest pseudo-version, so remember to tag releases. To see how a page will look, run go doc locally or preview with pkgsite, the open-source program that powers the site.

Keeping the API stable

Documentation is a promise, and so is an API. Go itself follows the Go 1 compatibility promise: code written for Go 1.0 still compiles today. Modules follow semantic versioning (vMAJOR.MINOR.PATCH) to make the same promise at library level:

  • A patch release (v1.2.1) fixes bugs and changes nothing visible.
  • A minor release (v1.3.0) adds features and stays compatible.
  • A major release (v2.0.0) may break compatibility, and since the import path must change with it (example.com/slug/v2), old and new versions can coexist in one program. See Go modules.
  • Versions below v1.0.0 make no compatibility promise, which is useful while you are still experimenting.

What counts as a breaking change

Removing or renaming an exported name, changing a function's parameters or results, and changing a type's meaning are obvious breaks. Some breaks are less obvious. Adding a method to an interface breaks everybody who implements it, and adding a field to a struct breaks callers who build it with an unkeyed literal like Point{1, 2}. The program below shows both. It does not compile, and the compiler messages are what your users would see after upgrading:

Go Changes that break callers (fails on purpose)

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.

The first error says that memStore does not implement Store because the method Delete is missing; the second says too few values in struct literal of type Point. Neither was a change in the callers' own code.

How to grow an API without breaking it

Compatible changes are easy to make if you plan for them:

  • Add, don't change. A new function, a new method on a struct, a new exported constant or a new field in a struct that users create with keyed literals is safe.
  • Keep interfaces small, and when you need an extra capability, define a second interface and let callers opt in through a type assertion. The standard library does this with io.WriterTo and fmt.Stringer.
  • Use options. A constructor with a variadic list of option functions (see constructors and options) can accept new settings forever without changing its signature.
  • Hide what you may want to change. Put implementation details in an internal/ directory or in unexported fields, so users cannot depend on them.
Go Evolving an API compatibly

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.

Before you release, check what changed. The gorelease tool compares your module against its previous version and tells you which version number the changes require; the apidiff tool does the same at the package level.

Terminal
go install golang.org/x/exp/cmd/gorelease@latest
gorelease                  # suggests the next version (patch, minor or major)
git tag v1.1.0 && git push origin v1.1.0

If you publish a version with a serious bug, you cannot delete it (the proxy keeps it forever), but you can mark it as unusable with a retract directive in go.mod, and publish a fixed version that contains the directive:

TEXT
retract v1.1.0 // Contains a deadlock in Maker.Make; use v1.1.1.

A checklist for good documentation

  • Every exported name has a doc comment that begins with its name.
  • The package has a // Package ... comment (in doc.go if long) that explains what it is for and shows the main entry points.
  • At least one Example function shows the most common use, with an // Output: comment.
  • Edge cases (empty input, errors, concurrency, zero value) are stated, not left to guesses.
  • Deprecated names say what to use instead.
  • The README lets a stranger install and run something in a minute.
  • Releases are tagged with semantic versions, and the changelog says what changed.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. How should a doc comment for the function Slug begin?

    By convention a doc comment is a full sentence that starts with the name of the declaration, so summaries read well in search results and go doc output.
  2. 2. How do you write a heading inside a doc comment (Go 1.19 and later)?

    Doc comments support # Heading lines. They must be separated from the other text by blank comment lines.
  3. 3. Which function name makes go doc show an example for the method Maker.Make?

    The pattern is Example, then the type, an underscore and the method. A further suffix starting with a lowercase letter (ExampleMaker_Make_empty) names variants.
  4. 4. Your v1 library adds a method to an exported interface. What happens to other packages that implement that interface?

    A type satisfies an interface only if it has all the methods. Adding one breaks existing implementers, so it needs a new major version or a separate optional interface.
  5. 5. How is a function marked as deprecated so tools can warn about it?

    The convention is a doc-comment paragraph starting with Deprecated:. Editors, pkg.go.dev and staticcheck recognize it.

Summary

  • A doc comment sits directly above an exported declaration and starts with its name; package comments start with Package name and can live in doc.go.
  • The syntax is plain: paragraphs, # headings, indented lists, indented code blocks, [Doc links] and URLs. gofmt normalizes it and go/doc/comment parses it.
  • go doc shows the documentation in your terminal, and pkg.go.dev renders it for every tagged public module, including license and examples.
  • ExampleXxx functions with // Output: are documentation that is tested; the name decides which declaration they attach to.
  • Write a README (install, smallest example, link, license) and a CHANGELOG, and mark old APIs with Deprecated: paragraphs.
  • Follow semantic versioning. Add rather than change, keep interfaces small, use options, and check with gorelease; use retract for broken releases.

Next: Building an HTTP Server