Documentation and APIs

Updated

July 30, 2026

Overview

Good documentation makes code usable. Go has built-in tools for extracting docs from source comments.

Writing Doc Comments

// Package math provides mathematical utilities.
//
// It includes functions for basic arithmetic and
// statistical calculations.
package math

// Pi represents the mathematical constant π.
const Pi = 3.14159

// Add returns the sum of a and b.
func Add(a, b int) int {
    return a + b
}

// Calculator provides stateful calculations.
type Calculator struct {
    // Result holds the current value.
    Result float64
}

Conventions

Start with the name being documented
Use complete sentences
First sentence is the summary

Examples

func ExampleAdd() {
    result := Add(2, 3)
    fmt.Println(result)
    // Output: 5
}

Viewing Docs

go doc fmt
go doc fmt.Println
go doc -all mypackage

pkg.go.dev

Public packages are automatically documented at:

https://pkg.go.dev/github.com/user/package

API Design Guidelines

// Accept interfaces, return structs
func Process(r io.Reader) (*Result, error)

// Use functional options
func NewServer(opts ...Option) *Server

// Clear error messages
return fmt.Errorf("user %d: %w", id, err)

Summary

Tool	Purpose
`go doc`	View documentation
`godoc`	Local doc server
pkg.go.dev	Public package docs
Examples	Testable documentation

Worked example

Example tests as executable docs (// Output: checked by go test).

Save as mathdoc.go and mathdoc_test.go. Then:

go mod init example
go test -v -run Example

// mathdoc.go
package main

// Mul returns a * b.
func Mul(a, b int) int { return a * b }

// mathdoc_test.go
package main

import "fmt"

func ExampleMul() {
    fmt.Println(Mul(6, 7))
    // Output: 42
}

func ExampleMul_zero() {
    fmt.Println(Mul(0, 99))
    // Output: 0
}

Expected output:

=== RUN   ExampleMul
--- PASS: ExampleMul (0.00s)
=== RUN   ExampleMul_zero
--- PASS: ExampleMul_zero (0.00s)
PASS

More examples

Godoc-shaped comments you can print with go doc.

// Package main demonstrates documentation comments.
//
// Start package comments with "Package <name>".
package main

// Answer is the answer to life, the universe, and everything.
const Answer = 42

// Double returns 2 * n.
func Double(n int) int { return n * 2 }

func main() {}

go doc Double

Runnable example

Save as docdemo.go and docdemo_test.go. Then:

go mod init example
go test -v
go doc -all .

// docdemo.go
// Package docdemo shows godoc-friendly comments and example tests.
//
// Doc comments become the package page on pkg.go.dev.
package main

import "fmt"

// Pi is a truncated mathematical constant for demos.
const Pi = 3.14159

// Add returns the sum of a and b.
//
// It does not check for overflow.
func Add(a, b int) int {
    return a + b
}

// Calculator keeps a running total.
type Calculator struct {
    // Result is the current accumulator value.
    Result int
}

// AddTo adds n to the calculator result and returns the new total.
func (c *Calculator) AddTo(n int) int {
    c.Result += n
    return c.Result
}

func main() {
    fmt.Println(Add(2, 3))
}

// docdemo_test.go
package main

import "fmt"

func ExampleAdd() {
    fmt.Println(Add(2, 3))
    // Output: 5
}

func ExampleCalculator_AddTo() {
    c := &Calculator{}
    fmt.Println(c.AddTo(4))
    fmt.Println(c.AddTo(6))
    // Output:
    // 4
    // 10
}