Documentation Comment

Go documentation comments are specially formatted comments placed immediately preceding a package, function, type, or variable declaration, without any intervening blank lines. The Go parser associates these comments with the subsequent Abstract Syntax Tree (AST) node, allowing tools like go doc and the pkg.go.dev portal to extract and render structured technical documentation.

Syntax and Association

To associate a comment with a declaration, it must be contiguous with the declaration. Standard convention dictates using single-line comments (//) rather than block comments (/* ... */), even for multi-line documentation.

The first sentence of the comment must be a single, complete summary sentence that begins with the exact name of the declared entity.

// Server represents an HTTP server handling client requests.
// It maintains the connection pool and routing table.
type Server struct {
    // ...
}

If a blank line separates the comment from the declaration, the Go toolchain treats it as a detached package-level comment, and it will not appear in the generated documentation for that entity.

// This comment is detached and will NOT be associated with Start.

func Start() {}

Formatting Rules (Go 1.19+)

The Go documentation parser recognizes a specific subset of formatting directives, heavily expanded in Go 1.19 to include standard structural elements.

Paragraphs Paragraphs are separated by a blank comment line (a line containing only //).

// Parse evaluates the input string and returns an AST.
//
// Parse will return a SyntaxError if the input is malformed.
func Parse(input string) error {
    return nil
}

Headings Headings are created using a hash symbol (#) followed by a space. The heading must be separated from surrounding paragraphs by blank comment lines.

// # Error Handling
//
// All errors returned by this package wrap the base Error type.

Preformatted Text (Code Blocks) Text indented by at least one space or tab relative to the surrounding comment text is treated as a preformatted block. It is rendered in a monospace font and preserves exact whitespace.

type Command struct{}

// Execute runs the command. Example:
//
//	cmd := NewCommand()
//	cmd.Execute()
func (c *Command) Execute() {}

Lists The parser recognizes unordered lists using dashes (-) or asterisks (*), and ordered lists using numbers (1.). List items must be indented, and the list must be separated from preceding paragraphs by a blank comment line.

// Supported modes:
//
//  - ModeRead: Opens the file for reading.
//  - ModeWrite: Opens the file for writing.

Links Links are declared using bracket notation. To maintain plain-text readability, Go does not support inline Markdown links (e.g., [Text](URL)). Instead, it supports documentation links, automatic URL linking, and reference links.

• Doc Links: [Name] links to the documentation of the entity named Name within the same package, or an imported package (e.g., [fmt.Println]).
• URL Links: Raw URLs are automatically linked. For custom display text, use a reference link by placing [Text] in the comment and defining the destination on a separate line using [Text]: URL.

// Write outputs the data to the [io.Writer].
// For more details, see the [official specification].
//
// [official specification]: https://example.com/spec
func Write() {}

Directives

Documentation comments support specific toolchain directives. The most prominent is the Deprecated: marker. It must begin with Deprecated: followed by an explanation and an alternative recommendation. The go doc tool and IDEs parse this to visually strike through the entity and warn developers.

// CalculateTotal computes the sum of the slice.
//
// Deprecated: Use [Sum] instead. CalculateTotal does not handle overflows.
func CalculateTotal(data []int) int {
    return 0
}

Package Documentation

To document an entire package, the documentation comment must be placed immediately above the package clause. For large packages, this is conventionally isolated in a dedicated file named doc.go.

// Package math provides basic constants and mathematical functions.
//
// # Precision
//
// All computations are performed using IEEE 754 64-bit floating-point numbers.
package math

Master Go with Deep Grasping Methodology!

Learn More