How do you link to another package's identifier from inside a Go doc comment?

## The syntax exists, and it is small Go doc comments are plain text with a handful of conventions, formalised in Go 1.19 when `gofmt` began reformatting doc comments into a canonical shape. There is no markup language to learn; there are five things. ### 1. Doc links A bracketed identifier becomes a link to that declaration. ```go // A Session is a live admin console attached to one terminal. // // Create one with [NewSession]. The writer it is given may be any // [io.Writer]; a [*bytes.Buffer] is convenient in tests. ``` The forms are `[Name]` for a declaration in the same package, `[Name.Method]` for a method on a local type, `[pkg.Name]` and `[pkg.Name.Method]` for another package, and a leading star is allowed — `[*bytes.Buffer]` — so the link reads naturally where a pointer type is meant. The package part must be resolvable: either the name the current file imports the package under, or a full import path such as `[golang.org/x/text/unicode/norm.NFC]` when the package is not imported. This is the detail people trip over — a link to a package you do not import, written with just its short name, does not resolve. And when a link does not resolve, nothing breaks. The tools leave the text exactly as you typed it, brackets included. That is a friendly failure mode for a build but an unfriendly one for a reader, because a typo shows up as literal brackets in the published documentation rather than as an error anyone gets told about. Reading the rendered output is the only check. ### 2. Headings A line whose text begins with `#` and a space is a heading: ```go // Package console renders an interactive admin terminal. // // # Lifecycle // // Every session must be closed to restore the terminal state. // // # Concurrency // // A session is owned by the goroutine that created it. ``` One `#` only — there is a single heading level, which is a deliberate limit on how much structure a comment can grow. Headings are worth it for a package comment with genuinely separate sections and are noise on a three-line function comment. ### 3. Lists An indented line starting with a bullet (`-`, `*`, `+`) or with a number followed by a period or bracket becomes a list item. A list must be separated from the paragraph above it by a blank comment line, and continuation lines are indented under the item. ### 4. Code blocks Any span of indented lines is rendered pre-formatted. This is how you show a short usage sketch or a sample of output inside a comment. Worth remembering: that text is *never compiled*, so it is the part of a doc comment most likely to be quietly wrong a year later — which is why a genuinely important usage sketch is better written as a runnable example function instead. ### 5. URL links Web links use a definition at the end of the comment: ```go // See the [operator runbook] before enabling destructive commands. // // [operator runbook]: https://example.com/runbook ``` The definitions are collected at the bottom of the comment, so the prose stays readable in the source. ## gofmt owns the layout Since the syntax was formalised, `gofmt` rewrites doc comments into a canonical form: it normalises list indentation, moves link definitions to the end, tidies heading spacing, and reflows nothing else. Two practical consequences. First, you do not have to get the whitespace right by hand — write it approximately and run the formatter. Second, the first time a repository formats with a modern toolchain, doc comments across the tree will show diffs; that is the reformatting, not a change of meaning. ## How much of this to use The honest answer is: links liberally, headings sparingly, everything else when the content demands it. Links are pure benefit — they cost one pair of brackets and turn a mention of a type into navigation, which matters most in exactly the place documentation is weakest, the sentence that says "pass this to the writer" without saying which writer. Headings and lists earn their place in a package overview and almost never in a comment on a single function. And a comment that has grown enough structure to need three headings and two lists is often a signal that the package needs a separate overview rather than a bigger comment. ## Checking your work Run `go doc` on the package or the symbol and read what comes out. Rendered output is where an unresolved link, a list that did not become a list, or a heading that did not take announce themselves; none of them is visible from staring at the `//` lines in an editor.