Go Doc Comments

Overview

Produce doc comments that render cleanly in go doc, pkgsite, and IDEs by following the Go project's official guidance. Apply this skill whenever documenting exported Go identifiers or packages.

When to Use

• Document exported Go packages, commands, types, funcs, consts, or vars.
• Review existing comments for compliance during code review or refactors.
• Convert informal inline comments into doc comments intended for pkgsite.

Avoid invoking this skill for unexported identifiers unless the repository mandates internal documentation parity.

Workflow

1. Locate the target declaration
   Place the comment immediately above the top-level declaration with no blank lines between the comment and the declaration.

2. Draft the lead sentence

   • Start package comments with Package <name> ... in complete sentences.
   • Start command package comments with the capitalized program name, e.g., Gofmt formats Go programs.
   • Start other doc comments with the identifier name followed by a verb phrase that explains what it does (e.g., Serve starts an HTTP server.).

3. Expand the description

   • Describe behavior, usage, and key arguments succinctly.
   • Link to related APIs using square brackets ([net/http]) so pkgsite creates hyperlinks.
   • Use semantic linefeeds (one sentence per line) when it improves diffs; pkgsite rewraps automatically.

4. Format structured content

   • Indent lists and code blocks with either a tab or two spaces so they render correctly.
   • Create numbered or bulleted lists with a leading tab/space and a marker (- or digits).
   • Avoid nested lists; rewrite as multiple paragraphs or mixed markers if hierarchy is essential.
   • Indent multi-line shell commands or code samples consistently, and add blank lines before and after blocks.

5. Preserve tone and accuracy

   • Use present tense and active voice.
   • Keep comments factual; avoid marketing language.
   • Mention exported error conditions, side effects, and concurrency guarantees as needed.

6. Validate rendering

   • Run go doc <pkg>.<Symbol> or view via pkgsite to confirm wrapping, lists, and links render as expected.
   • Run gofmt (Go 1.19+) to ensure indentation aligns with the doc-comment heuristics.
   • Adjust spacing if gofmt highlights ambiguous paragraphs (add or remove blank lines).

Quick Checklist

• Begin with the correct identifier prefix (Package, symbol name, or command).
• Keep sentences complete and punctuated.
• Use links [package] or [Type.Method] for cross references.
• Indent lists, code blocks, and shell snippets.
• Avoid nested lists; restructure instead.
• Verify formatting with go doc and gofmt.

Good and Bad Examples

Good – Package comment introducing scope and linking APIs

// Package cache provides in-memory caches with automatic eviction policies.
//
// The package exposes [LRU] and [TTL] caches that guard concurrent access with
// sync.RWMutex. Use [NewLRU] for bounded caches and [NewTTL] when entries expire
// after a fixed duration.
package cache

Why it works:

• Opens with Package cache.
• Summarises primary types and cross-links constructors.
• Uses short sentences and a blank line for readability.

Bad – Missing identifier prefix and malformed list

// Provides caches that can evict entries.
// - LRU policy
// - TTL policy
package cache

Issues:

• First sentence omits the Package prefix, so the synopsis becomes unclear.
• List items are unindented, so pkgsite renders them as plain text.
• Does not explain when to choose each policy.

Good – Function comment covering behavior and errors

// Fetch retrieves the value for key from the remote store.
//
// Fetch retries transient failures using exponential backoff and returns an
// error that implements [net.Error] when the deadline expires.
func Fetch(ctx context.Context, key string) ([]byte, error) {

Highlights:

• Begins with the function name.
• Documents retry policy and exported error semantics.
• Uses semantic linefeeds to keep diffs focused on changed sentences.

Bad – Narrative tone and misleading code block

// This function is going to try to get your data, but it might fail!!
// If it fails we waited too long and the store is DEAD.
//    retryCount++
func Fetch(ctx context.Context, key string) ([]byte, error) {

Problems:

• Uses second-person narrative and emotional language.
• Fails to mention the function name or concrete behavior.
• Indented retryCount++ is treated as a code block even though it provides no context.

Validation Tools

• go doc <package> or go doc <package>.<Symbol> – preview rendered documentation.
• pkgsite (local or hosted) – inspect pkgsite rendering.
• gofmt – verify indentation heuristics for doc comments.

Quick Checklist

• Comment sits immediately above the exported declaration with no blank line.
• Lead sentence starts with Package, the program name, or the symbol name.
• Sentences are complete, factual, and written in present tense.
• Links use square brackets ([pkg.Symbol]) to enable pkgsite cross references.
• Lists and code snippets are indented; nested lists are avoided.
• Error contracts, side effects, and concurrency guarantees are documented.
• go doc preview looks correct and gofmt leaves formatting untouched.