go-documentation

Go 文档

资源路由

• scripts/check-docs.sh - 检查导出的函数、类型、方法、常量和包是否缺少文档注释时运行。
• scripts/check-docs-ast.go - 由 check-docs.sh 调用的实现辅助程序；更改文档分析行为时，请修改此文件。
• assets/doc-template.go - 开始编写带文档的新包或导出 API 时使用。
• references/CONVENTIONS.md - 编写参数、上下文行为、并发安全、清理、错误或命名结果的文档时阅读。
• references/EXAMPLES.md - 添加可运行示例或包示例时阅读。
• references/FORMATTING.md - 设置 Godoc 列表、段落、链接和代码块格式时阅读。

---

文档注释

规范性要求：所有顶层导出名称都必须有文档注释。

基本规则

1. 以所描述对象的名称开头
2. 名称前可以加冠词（“a”“an”“the”）
3. 使用完整句子（首字母大写，并以标点结尾）

// A Request represents a request to run a command.
type Request struct { ...

// Encode writes the JSON encoding of req to w.
func Encode(w io.Writer, req *Request) { ...

行为不明显的未导出类型/函数也应添加文档注释。

验证：添加文档注释后，运行 bash scripts/check-docs.sh，确认没有导出符号缺少文档。继续之前，请修复所有遗漏。

---

注释句子

规范性要求：文档注释必须是完整句子。

• 首词首字母大写，并以标点结尾
• 例外：如果含义清楚，可以以首字母未大写的标识符开头
• 结构体字段的行尾注释可以是短语

---

注释行长度

建议：尽量控制在约 80 列，但没有硬性限制。

根据标点断行。不要拆分较长的 URL。

---

结构体文档

使用章节注释对字段分组。为可选字段标注默认值：

type Options struct {
    // General setup:
    Name  string
    Group *FooGroup

    // Customization:
    LargeGroupThreshold int // optional; default: 10
}

---

包注释

规范性要求：每个包必须且只能有一条包注释。

// Package math provides basic constants and mathematical functions.
package math

• 对于 main 包，使用二进制文件名：// The seed_generator command ...
• 对于较长的包注释，使用 doc.go 文件

---

应记录的内容

建议：记录不明显的行为，而非显而易见的行为。

主题	在以下情况下记录……	以下情况下跳过……
参数	不明显的行为、边缘情况	重述类型签名
上下文	行为与标准取消行为不同	返回标准的 ctx.Err()
并发	线程安全性不明确（例如，读取操作会修改数据）	只读操作是安全的，修改操作是不安全的
清理	始终记录资源释放	—
错误	哨兵值、错误类型（使用 *PathError）	—
命名结果	同类型参数有多个，名称体现操作	仅凭类型已足够清楚

关键原则：

• 上下文取消时返回 ctx.Err() 属于默认行为——不要重复说明
• 默认认为只读操作是并发安全的，修改操作不是——不要重复说明
• 始终记录清理要求（例如，Call Stop to release resources）
• 错误类型文档中使用指针（*PathError），以确保 errors.Is/errors.As 正常工作
• 不要仅为启用裸返回而命名结果——清晰度优先于简洁性

---

可运行示例

建议：在测试文件（*_test.go）中提供可运行示例。

func ExampleConfig_WriteTo() {
    cfg := &Config{Name: "example"}
    cfg.WriteTo(os.Stdout)
    // Output:
    // {"name": "example"}
}

示例会显示在附加到所记录元素的 Godoc 中。

---

快速参考

主题	关键规则
文档注释	以名称开头，使用完整句子
行长度	约 80 个字符，优先考虑可读性
包注释	每个包一条，置于 package 声明上方
参数	仅记录不明显的行为
上下文	记录与默认行为不同的情况
并发	记录不明确的线程安全性
清理	始终记录资源释放
错误	记录哨兵值和类型（注意指针）
示例	在测试文件中使用可运行示例
格式	段落之间留空行，代码块使用缩进

---

相关技能

• 命名规范：为文档注释所描述的标识符选择名称时，请参阅 go-naming
• 测试示例：编写出现在 godoc 中的可运行 Example 测试函数时，请参阅 go-testing
• Lint 强制检查：使用 revive 或其他 linter 强制要求存在文档注释时，请参阅 go-linting
• 风格原则：在文档的详尽程度与清晰简洁之间取得平衡时，请参阅 go-style-core