typefox/agent-skills/go-documentation

Go Documentation

Go treats documentation as part of the toolchain. go doc reads comments locally, pkg.go.dev publishes them, and gofmt normalizes their markup. The conventions here come from the official spec at https://go.dev/doc/comment — tools depend on them, so they are not stylistic preferences.

Coming from TypeScript

A Go doc comment is a plain // comment above a declaration — there are no tags, and almost none of the Markdown that JSDoc/TSDoc allow. These are the habits that silently produce wrong or unrendered docs; reach for the Go column instead.

These habits usually show up together. Porting one JSDoc comment typically means fixing several rows in the table at once. Before — reads fine in an editor, renders broken or missing on pkg.go.dev:

// `Cache` is a simple LRU cache.
//
// @param size max number of entries
// @returns a new Cache
func NewCache(size int) *Cache { ... }
 
// Method to look up `key`, returns true if found.
// See the [tuning guide](https://example.com/cache-tuning) for eviction details.
func (c *Cache) Get(key string) (string, bool) { ... }

After:

// Cache is a simple LRU cache.
type Cache struct{ ... }
 
// NewCache creates a Cache that holds at most size entries.
func NewCache(size int) *Cache { ... }
 
// Get reports whether key is present in the cache, returning its
// value if so. See https://example.com/cache-tuning for eviction details.
func (c *Cache) Get(key string) (string, bool) { ... }

Reference files

Load on demand; don't read upfront.

• references/comment-syntax.md — full markup grammar (paragraphs, headings, links, doc links, lists, code blocks, notes, deprecations, directives), the gofmt reformatting rules, and the pitfalls that produce unintended code blocks or broken lists. Read it for any comment richer than plain prose, or when gofmt reformats a comment unexpectedly.
• references/examples.md — testable Example functions: naming rules (including the _suffix lower-case constraint), // Output: / // Unordered output: assertions, whole-file examples. Read it when adding examples or when one misbehaves.
• references/publishing.md — how pkg.go.dev discovers and indexes modules via proxy.golang.org: go.mod and license requirements, semantic versioning, README rendering, source links, retraction, removal. Read it before publishing, or when a module isn't showing up.
• references/pkgsite-preview.md — running pkgsite to preview a module's docs locally before publishing. Read it when iterating on comments.

The attachment rule

A doc comment is a comment placed immediately before a top-level package, const, func, type, or var declaration, with no blank line between them. The blank line is what go/doc uses to tell a doc comment from an unrelated comment above it. Get it wrong and the docs vanish from go doc and pkg.go.dev even though the comment is still in the source. Every exported (capitalized) name should have one.

First sentence names the symbol

go doc, IDE hovers, and pkg.go.dev search all surface the first sentence alone as the one-line summary — often with no symbol name beside it. So the sentence must name the symbol itself.

Use reports whether for booleans, not returns true if — it is the standard-library convention and reads better in the index.

Package documentation

The package comment is the most important comment in a module: it is what pkg.go.dev indexes and shows on the landing page, and what answers "what is this for?". Write the first sentence as a self-contained one-liner starting with Package <name> — assume the reader sees nothing else.

Good: Package errgroup provides synchronization, error propagation, and Context cancellation for groups of goroutines working on subtasks of a common task. Weak: This package is a small library for working with goroutines. — no Package errgroup, says nothing specific.

Put the comment in a dedicated doc.go (only the comment plus the package clause). It is a stable home that survives the file renames that silently orphan a comment attached to a regular source file, and it signals where package docs live. Only one file may hold the package comment; multiple are concatenated in an unspecified order.

// Package json implements encoding and decoding of JSON as defined in
// RFC 7159. The mapping between JSON and Go values is described
// in the documentation for the [Marshal] and [Unmarshal] functions.
package json

For packages beyond a handful of symbols, add a short overview after the first paragraph pointing at the main entry points with doc links, so the page doesn't render as a wall of symbols:

// Package http provides HTTP client and server implementations.
//
// [Get], [Head], [Post], and [PostForm] make HTTP (or HTTPS) requests:
//
//  resp, err := http.Get("http://example.com/")
//
// The client must close the response body when finished with it:
//
//  defer resp.Body.Close()
//
// For control over headers and redirect policy, create a [Client] ...
package http

README vs doc.go

Modules typically need both, for two readers — don't paste the same text into both. The README.md is read on the host (GitHub/pkg.go.dev landing area) by someone not yet using the module: pitch, go get, prerequisites, badges, a quick-start snippet. The package comment is read via go doc, IDE hover, and the pkg.go.dev API view by someone who already imported it: technical overview, main types and call flow, invariants, error and concurrency semantics, doc links to key symbols. After go get the README disappears from daily work — a package overview that only says "see README" loses the toolchain integration that makes Go docs distinctive.

For a multi-package module: one README.md at the root, and a package comment (usually a doc.go) in every package and subpackage — not a README per package.

Commands (package main)

For a binary, the package comment describes the program, not a Go API. Use semantic linefeeds (one sentence per line); gofmt preserves them, giving cleaner diffs.

// Gofmt formats Go programs.
// It uses tabs for indentation and blanks for alignment.
//
// Usage:
//
//  gofmt [flags] [path ...]
//
// The flags are:
//
//  -l
//      List files whose formatting differs from gofmt's.
package main

Function and method documentation

Pick the first-sentence pattern from the table, then add what a caller needs. Refer to parameters and results by name in prose, without backticks; avoid names like a or s that read as ordinary words.

• Special cases as an indented block:

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

• Concurrency safety. Top-level functions are conventionally assumed safe for concurrent use; methods are assumed not safe (single goroutine at a time). State any exception explicitly.
• Complexity when it matters to callers (e.g. sort.Sort documents its O(n log n) comparisons).
• Deprecation via a Deprecated: paragraph — always name the replacement. See references/comment-syntax.md § Deprecations.

Document behavior callers can rely on, not the algorithm. "Uses quicksort internally" locks the implementation behind the doc contract; a maintainer who switches to timsort silently breaks it.

Type documentation

Start with A <Type> / An <Type> describing what an instance represents, then add whichever apply:

• Zero value. If the zero value is meant to work, say so — readers can only rely on it if documented: The zero value for Buffer is an empty buffer ready to use.
• Concurrency safety. Default is "not safe"; anything stronger must be explicit.
• Fields. Either the type comment describes exported fields collectively, or each field carries its own comment — pick one per type.

// 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
}