Doc Comments

## Go has no documentation syntax — it has a placement rule Most languages mark documentation with a special token: a `/**` opener, a `"""` docstring, an attribute. Go does none of that. A **doc comment** is an ordinary comment — a run of `//` lines, or a single `/* */` block — that sits **immediately before** the thing it documents, with **no blank line** in between. That adjacency is the entire attachment mechanism. When the toolchain builds documentation it parses the file, and for each declaration it takes the comment group that ends on the line directly above it. Anything separated by a blank line is a free-floating comment: valid Go, invisible to documentation. ```go // Fetch returns the current price for id. func Fetch(id string) (int, error) { ... } // Not documentation — the blank line below detaches this. func Store(id string, price int) error { ... } ``` Run `go doc` on that package and `Fetch` has a description while `Store` has none. Nothing warns you; the comment is still there in the source, doing nothing for the reader who only ever sees the rendered page. ## What can carry a doc comment - **The package clause.** A comment group immediately above `package name` is the package comment — the opening paragraph of the whole package's page. - **Top-level declarations:** `func`, `type`, `var`, `const`, and methods. - **Grouped declarations.** A comment above `const (` or `var (` documents the group as a unit. Individual specs inside the parentheses may carry their own comments, which are shown per constant. This is why a block of related status codes usually has one paragraph above the group explaining the set, plus short comments per value. - **Struct fields and interface methods.** Comments above a field, or on the same line after it, are kept and displayed when the type is printed. Comments **inside a function body** are never documentation. They are notes to the next person editing the code, and no tool surfaces them. ## The identifier-first convention By convention a doc comment starts with the name it documents, as a complete sentence: `// Fetch returns the current price for id.` This is not enforced by the compiler, but it matters for two practical reasons. First, the **first sentence is used as the summary** wherever a list of symbols is shown, so it has to stand alone away from the declaration. Second, a reader scanning a rendered page sees the sentence, not your source layout, so a summary beginning with *It* or *This function* reads as an orphan. ## Exported versus unexported Documentation is not limited to exported names. You can — and on a package other people maintain, should — document unexported helpers. They are simply hidden by default: `go doc ./pkg` shows exported symbols only, and `go doc -u ./pkg` includes unexported ones. The public documentation site never shows them at all, which is one reason a doc comment on an unexported function is aimed at your colleagues reading source, while a doc comment on an exported one is aimed at a stranger who will read nothing else. ## Why there is no `@param` Go's documentation is deliberately prose. There are no structured tags for parameters, returns or errors; you write sentences that name the parameters instead: *reports whether*, *returns ErrNotFound if*, *the caller must call Close*. Only a handful of conventions are machine-read at all: the leading identifier name, the small formatting syntax for headings, lists and links, and a paragraph beginning `Deprecated:`. Everything else is text for a human. ## The failure this prevents The package page is often the **only** onboarding a stranger gets — they will not open your source. Detached comments, comments inside the function body, and exported functions with nothing above them all produce the same result: a page listing signatures with no prose. When you review a change to an exported declaration, read what `go doc` prints for it rather than what the diff shows, because the diff makes a detached comment look attached.