go-documentation

Go 文档

Godoc 不是自由格式的散文，而是工具链会渲染的一套约定。 遵循约定的注释会成为 pkg.go.dev 上可浏览的文档； 不遵循约定的注释则会成为噪声。

社区默认规则。如果项目技能或 Agent 配置规则明确 取代了 go-documentation，则优先遵循该规则。

按需加载的详细参考资料：

• references/project-docs.md — 库和服务的 README 模板、 CHANGELOG、llms.txt、CONTRIBUTING。

只有在以下摘要不足以满足需要时，才阅读参考文件。

1. 文档注释格式

每个导出的标识符都要有文档注释。注释以标识符的名称开头， 并且是一个完整的句子：

// ✅ Good
// ParseDuration parses a duration string such as "300ms" or "2h45m".
// It returns an error if the string is not a valid duration.
func ParseDuration(s string) (Duration, error) { ... }

// ❌ Bad — doesn't start with the name, fragment, restates signature
// this function parses durations
func ParseDuration(s string) (Duration, error) { ... }

• 相关的常量或变量组可以共用一条注释，写在代码块上方： const (...) 组上方写 // Common HTTP methods.。
• 未导出的标识符：如果用途无法从名称中明显看出，则添加注释—— 格式相同，但不作强制要求。
• 说明调用方需要了解的内容：行为、错误条件、nil/零值处理、 并发安全性。不要描述实现方式。

2. 包文档

每个包在 package 声明处添加一条包注释。超过几句话时， 将其放在专门的 doc.go 文件中：

// Package retry implements backoff strategies for retrying failed
// operations.
//
// The zero value of Policy retries three times with exponential
// backoff. Use functional options to customize:
//
//	p := retry.NewPolicy(retry.WithMaxAttempts(5))
//	err := p.Do(ctx, fetchUser)
package retry

• 以 "Package ..." 开头。
• 缩进的行（一个制表符）会渲染为代码块。
• main 包：注释描述命令及其标志—— 它会成为该命令的文档。

3. 文档链接和格式（Go 1.19+）

// Fetch retrieves the resource. It honors the deadline of ctx and
// returns [ErrNotFound] if the resource does not exist.
//
// For batch retrieval use [Client.FetchAll]. See the [net/http]
// package for transport configuration.
func (c *Client) Fetch(ctx context.Context, id string) (*Resource, error)

• [Name]、[Type.Method]、[pkg/path] 会在 pkg.go.dev 上变成超链接。
• 以 # 开头的行是标题（较少使用；仅用于较长的包文档）。
• 列表：以空格和项目符号开头的行。列表层级应保持简单。

4. 可测试示例

示例函数是由编译器检查的文档。将它们放在 <pkg>_test 包的 example_test.go 中：

func ExampleParseDuration() {
    d, _ := ParseDuration("1h30m")
    fmt.Println(d.Minutes())
    // Output: 90
}

// Method example: ExampleType_Method
func ExamplePolicy_Do() { ... }

// Second example for the same symbol: suffix
func ExampleParseDuration_negative() { ... }

• // Output: 注释会使其成为测试——如果打印的输出不同， go test 就会失败。不带该注释的示例会编译，但不会运行。
• 为每个非平凡的导出 API 编写示例。示例会直接显示在 pkg.go.dev 上对应符号的下方。

5. 弃用

// Fetch retrieves the resource.
//
// Deprecated: Use [Client.FetchContext] instead, which honors
// context cancellation.
func (c *Client) Fetch(id string) (*Resource, error)

• 该段落必须严格以 Deprecated: 开头。
• 始终注明替代项。
• 工具（gopls、staticcheck、pkg.go.dev）会自动显示这些信息。

6. 不要写什么

// ❌ Noise — restates the code
// GetName returns the name.
func (u *User) GetName() string { return u.name }

// ❌ Maintenance history — belongs in git
// Changed 2024-03-01 by alice: added caching.

// ❌ Commented-out code kept "for reference"

如果文档注释只能复述函数签名，就改进名称，直到注释能说明签名 无法表达的内容——或者，在文档齐全的 API 中，为保持对称而接受 最简注释。

7. 项目级文档

• README — 库项目应首先介绍其用途、安装方式、最简可运行示例， 并提供 pkg.go.dev 链接，而不是重复列出 API。服务项目应首先介绍 如何运行、配置表（尽可能从配置结构体生成），以及健康检查、指标 和运行手册的位置。
• CHANGELOG — 使用 Keep a Changelog 的章节（Added、Changed、 Deprecated、Removed、Fixed、Security），面向模块的用户编写， 而非作为提交日志。
• llms.txt — 放在文档根目录的简短 Markdown 索引，引导 AI 助手 查阅 API 参考和示例。
• Go 1.27+：go doc example.com/[email protected] 可在不更改 go.mod 的情况下读取其他版本的文档；go doc -ex 会列出可执行示例。

模板：references/project-docs.md。

可执行验证

go vet ./...                  # flags some malformed doc comments
gofmt -l .                    # Go 1.19+ gofmt normalizes doc comments
go test ./...                 # runs Example functions with Output
go doc ./mypkg Symbol         # render what users will actually see

若要查看可浏览的预览，请在可用时运行本地 pkgsite： go run golang.org/x/pkgsite/cmd/pkgsite@latest，然后打开该模块。

验证清单

1. 每个导出的标识符都有以其名称开头的文档注释
2. 包含包注释（“Package ...”）；如果内容较长，则放在 doc.go 中
3. 为导出的 API 记录错误条件以及 nil/零值行为
4. 在调用者可能产生误判时，说明并发安全性
5. 在正文中使用 [Symbol] 文档链接，而非裸名称
6. 为重要的导出 API 编写带有 // Output: 的示例函数
7. 弃用说明使用准确格式 Deprecated: ，并指出替代方案
8. 不包含复述函数签名、记录历史或保留死代码的注释
9. 启用示例后，go test ./... 可以通过
10. README 开篇说明用途并提供可运行的示例；用户可见的更改需更新 CHANGELOG