go-documentation

Files (13)

• SKILL.md
• evals.json · evals/
• go.mod · evals/files/jsdoc-comments/
• tokenbucket.go · evals/files/jsdoc-comments/
• README.md · evals/files/package-overview/
• go.mod · evals/files/package-overview/
• store.go · evals/files/package-overview/
• go.mod · evals/files/testable-examples/
• slug.go · evals/files/testable-examples/
• comment-syntax.md · references/
• examples.md · references/
• pkgsite-preview.md · references/
• publishing.md · references/

SKILL.md (first lines)

# Go Documentation

Go treats documentation as part of the toolchain. `go doc` reads comments locally, [pkg.go.dev](https://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.

| TypeScript / JSDoc habit                 | What Go actually does                                                                                     |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `@param`, `@returns`, `@throws` tags     | No tags exist. Name params and results in prose ("It returns the number of bytes written"). Types are in the signature — don't restate them. |
| `` `inline code` `` backticks            | Backticks (and `'single quotes'`) render as curly ‘quotes’. There is no inline-code markup — use a doc link `[Name]` for a symbol, plain text otherwise. |
| Markdown link `[text](url)`              | Not a link. Use a bare URL, or reference style: `[text]` in prose plus `[text]: https://…` defined at the end of the comment. |
| `{@link Foo}` cross-reference            | Not recognized, renders as literal text. Use a doc link: `[Foo]`.                                         |
| Fenced ```` ``` ```` blocks, `**bold**`  | No fences, no emphasis. A code block is any line indented by one tab; `**bold**` renders literally.       |
| `/** ... */` Javadoc-style block comment | Valid Go syntax, and it *does* attach as the doc comment — but `gofmt` recognizes the leading-`*` pattern and deliberately leaves it untouched, so the un-stripped `*` on every line makes `go doc`/pkg.go.dev render it as a mangled code block. Use a plain `//` on every line instead. |
| `@example` with a snippet                | Examples are real compiled functions (`func ExampleFoo()`) in `_test.go`, run by `go test`. See `references/examples.md`. |
| `@deprecated`                            | A paragraph beginning with the exact prefix `Deprecated: `.                                               |
| Summary in any phrasing                  | The first sentence must start with the symbol name: `Foo returns…`, `Package foo…` (see the table below). |
| README is the docs (npmjs.com)           | pkg.go.dev and `go doc` show the **package comment**, in addition to the README, above the API.           |
| Indent comment text freely               | Any indented line becomes a code block. Keep prose flush left.                                            |

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:

```go
// `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:

```go
// 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.

| Symbol kind            | First-sentence pattern                | Example                                                                         |
| ---------------------- | ------------------------------------- | ------------------------------------------------------------------------------- |
| Package                | `Package <name> ...`                  | `Package path implements utility routines for manipulating slash-separated paths.` |
| Command (`main`)       | `<Command> ...` (capitalized)         | `Gofmt formats Go programs.`                                                     |
| Type                   | `A <Type> ...` / `An <Type> ...`      | `A Reader serves content from a ZIP archive.`                                    |
| Function (returns)     | `<Function> returns ...`              | `Quote returns a double-quoted Go string literal representing s.`                |
| Function (side effect) | `<Function> <verb> ...`               | `Exit causes the current program to exit with the given status code.`            |
| Function (bool result) | `<Function> reports whether ...`      | `HasPrefix reports whether the string s begins with prefix.`                     |
| Constant / variable    | `<Name> is ...` / `<Name> <verb> ...` | `Version is the Unicode edition from which the tables are derived.`              |

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.

```go
// 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:

```go
// 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`)

From TypeFox/agent-skills, MIT.

More from TypeFox/agent-skills