go-documentation

Go Documentation

Godoc is not free-form prose — it's a convention the toolchain renders. Comments that follow the convention become browsable documentation on pkg.go.dev; comments that don't become noise.

1. Doc Comment Form

Every exported identifier gets a doc comment. It starts with the identifier's name and is a complete sentence:

// ✅ Good
// ParseDuration parses a duration string such as "300ms" or "2h45m".
// It returns an error if the string is not a valid duration.
func ParseDuration(s string) (Duration, error) { ... }

// ❌ Bad — doesn't start with the name, fragment, restates signature
// this function parses durations
func ParseDuration(s string) (Duration, error) { ... }

• Groups of related constants/variables may share one comment on the block: // Common HTTP methods. above the const (...) group.
• Unexported identifiers: comment when the purpose isn't obvious from the name — same form, no obligation.
• Say what the caller needs: behavior, error conditions, nil/zero-value handling, concurrency safety. Not the implementation.

2. Package Documentation

One package comment per package, on the package clause. For more than a few sentences, put it in a dedicated doc.go:

// Package retry implements backoff strategies for retrying failed
// operations.
//
// The zero value of Policy retries three times with exponential
// backoff. Use functional options to customize:
//
//	p := retry.NewPolicy(retry.WithMaxAttempts(5))
//	err := p.Do(ctx, fetchUser)
package retry

• Begins with "Package ...".
• Indented lines (one tab) render as code blocks.
• main packages: the comment describes the command and its flags — it becomes the command's documentation.

3. Doc Links and Formatting (Go 1.19+)

// Fetch retrieves the resource. It honors the deadline of ctx and
// returns [ErrNotFound] if the resource does not exist.
//
// For batch retrieval use [Client.FetchAll]. See the [net/http]
// package for transport configuration.
func (c *Client) Fetch(ctx context.Context, id string) (*Resource, error)