godoc-comments

name	godoc-comments
description	Write proper Go documentation comments for packages, types, funcs, consts, and vars. Use when writing, reviewing, or improving godoc comments. Covers naming conventions, syntax (headings, links, lists, code blocks), and common mistakes.
argument-hint	[identifier or file]

Go Doc Comments

Write documentation comments that render correctly in go doc, pkg.go.dev, and IDEs. Every exported (capitalized) name should have a doc comment.

Quick Reference

Declaration	First Sentence Pattern	Example
Package	"Package <name>..."	// Package path implements utility routines...
Command	"<Name>..." (capitalized)	// Gofmt formats Go programs.
Type	"A <Name>..." or "An <Name>..."	// A Reader serves content from a ZIP archive.
Func (return)	"<Name> returns..."	// Quote returns a double-quoted Go string literal.
Func (action)	"<Name> causes/does..."	// Exit causes the current program to exit...
Func (boolean)	"<Name> reports whether..."	// HasPrefix reports whether s begins with prefix.
Const group	Describe the set	// The result of Scan is one of these tokens...
Single const	Complete sentence	// Version is the Unicode edition...

Package Comments

Place in one source file per package (they concatenate if in multiple files).

// Package path implements utility routines for manipulating slash-separated
// paths.
//
// The path package should only be used for paths separated by forward
// slashes, such as the paths in URLs. This package does not deal with
// Windows paths with drive letters or backslashes; to manipulate
// operating system paths, use the [path/filepath] package.
package path

Type Comments

Explain what instances represent. Document concurrency safety if stronger than "single goroutine at a time." Document zero value meaning if not obvious.

// A Buffer is a variable-sized buffer of bytes with Read and Write methods.
// The zero value for Buffer is an empty buffer ready to use.
type Buffer struct { ... }

// Regexp is the representation of a compiled regular expression.
// A Regexp is safe for concurrent use by multiple goroutines,
// except for configuration methods, such as Longest.
type Regexp struct { ... }

For structs with exported fields, explain fields in doc comment or per-field:

// A LimitedReader reads from R but limits the amount of
// data returned to just N bytes. Each call to Read
// updates N to reflect the new amount remaining.
// Read returns EOF when N <= 0.
type LimitedReader struct {
    R   Reader // underlying reader
    N   int64  // max bytes remaining
}

Func Comments

Focus on what the caller needs to know: return values or side effects. Document special cases explicitly.

// Sqrt returns the square root of x.
//
// Special cases are:
//
//	Sqrt(+Inf) = +Inf
//	Sqrt(±0) = ±0
//	Sqrt(x < 0) = NaN
//	Sqrt(NaN) = NaN
func Sqrt(x float64) float64

// Copy copies from src to dst until either EOF is reached
// on src or an error occurs. It returns the total number of bytes
// written and the first error encountered while copying, if any.
//
// A successful Copy returns err == nil, not err == EOF.
func Copy(dst Writer, src Reader) (n int64, err error)

// Close returns the connection to the connection pool.
// All operations after a Close will return with ErrConnDone.
// Close is safe to call concurrently with other operations.
func (c *Conn) Close() error

Do NOT document internal algorithms—those go in code comments.

Const and Var Comments

Grouped declarations can share a comment:

// Generic file system errors.
// Errors returned by file systems can be tested against these errors
// using errors.Is.
var (
    ErrInvalid    = errInvalid()    // "invalid argument"
    ErrPermission = errPermission() // "permission denied"
    ErrExist      = errExist()      // "file already exists"
)

// The result of Scan is one of these tokens or a Unicode character.
const (
    EOF = -(iota + 1)
    Ident
    Int
    Float
)

Doc Comment Syntax

Headings

Use # prefix (Go 1.19+):

// Package strconv implements conversions to and from string representations.
//
// # Numeric Conversions
//
// The most common numeric conversions are [Atoi] and [Itoa].
package strconv

Links and Doc Links

• [text] — link to exported identifier in current package
• [pkg.Name] — link to identifier in another package
• [text]: URL — define external URL (goes at end of comment)

// ReadFrom reads data from r until EOF and appends it to the buffer.
// Any error except [io.EOF] encountered during the read is also returned.
// If the buffer becomes too large, ReadFrom will panic with [ErrTooLarge].
//
// For more details, see the [JSON and Go] article.
//
// [JSON and Go]: https://golang.org/doc/articles/json_and_go.html

Lists

Indent with spaces. Bullet lists use -. Numbered lists use 1., 2..

// Clean returns the shortest path name equivalent to path
// by applying the following rules iteratively:
//
//  1. Replace multiple slashes with a single slash.
//  2. Eliminate each . path name element.
//  3. Eliminate each inner .. path name element.
func Clean(path string) string

// PublicSuffixList provides the public suffix of a domain. For example:
//   - the public suffix of "example.com" is "com",
//   - the public suffix of "foo1.foo2.foo3.co.uk" is "co.uk".
type PublicSuffixList interface { ... }

Code Blocks

Indent with tab. Insert blank lines before and after.

// Search uses binary search to find and return the smallest index i
// in [0, n) at which f(i) is true.
//
// As a more whimsical example, this program guesses your number:
//
//	func GuessingGame() {
//		answer := sort.Search(100, func(i int) bool {
//			return s != "" && s[0] == 'y'
//		})
//		fmt.Printf("Your number is %d.\n", answer)
//	}
func Search(n int, f func(int) bool) int

Common Mistakes

Unindented Lists Become Code Blocks

Wrong:

// Features:
// 1) First feature.
// 2) Second feature.

Renders as: "Features:" paragraph, then "1) First feature. 2) Second feature." paragraph, then a code block with the continuation.

Correct:

// Features:
//
//  1. First feature.
//  2. Second feature.

Indented Continuation Lines Become Code Blocks

Wrong:

// TODO Revisit this design. It may make sense to walk those nodes
//      only once.

The indented second line becomes a code block.

Correct:

// TODO: Revisit this design. It may make sense to walk those nodes
// only once.

Nested Lists Not Supported

Go doc comments do not support nested lists. Rewrite to avoid nesting or mix list markers (numbered outer, bullet inner).

Deprecation Notices

Start paragraph with Deprecated::

// Reset zeros the key data and makes the Cipher unusable.
//
// Deprecated: Reset can't guarantee that the key will be entirely removed from
// the process's memory.
func (c *Cipher) Reset()

Notes

Use MARKER(uid): format for TODO, BUG, etc:

// TODO(user1): refactor to use standard library context
// BUG(user2): not cleaned up
var ctx context.Context

Directive Placement

Directives like //go:generate go at the end of the doc comment, after a blank line:

// An Op is a single regular expression operator.
//
//go:generate stringer -type Op -trimprefix Op
type Op uint8