很多 Go 开发者看到标准库或 pkg.go.dev 上整洁的 API 页面时，会以为那是一套额外维护的文档系统。实际上，Go 的文档大多直接来自源码注释，写法是否规范，会直接影响别人理解和使用你的包。
这篇文章按“文档是怎样生成的、哪些注释最关键、如何本地检查效果”三个问题来梳理。看完之后，你可以判断一段注释是否符合 godoc 习惯，也能快速搭起一套更适合团队协作的 Go 文档写法。
先理解规则：Go 文档是怎么从注释生成的
godoc 是 Go 语言的文档工具，它会直接解析 Go 源码中的注释并生成 API 文档。虽然官方文档站点在 2019 年从 godoc.org 迁移到了 pkg.go.dev，但核心规则并没有变：注释就是文档本身。
这套机制和很多语言不太一样。Go 不要求你使用复杂的注释标签，也不需要额外的文档描述语言，只要遵循几条约定，源码里的注释就能变成结构清晰的文档页面。这也是 Go 一贯的思路：规则少，但要求一致。
理解这一点很重要，因为它决定了文档工作不是“写完代码后再补一份说明”，而是在写导出 API 时，顺手把使用者真正需要的信息放到注释里。
最关键的两类注释：包注释和函数注释
包注释决定读者看到的第一印象
包注释是整个包的入口说明，通常写在文件顶部、紧挨着 package 声明之前。规范写法一般以 Package <包名> 开头，再用一两段话说明这个包解决什么问题、适合在什么场景下使用。
// Package validator 提供数据校验功能
// 支持字段级规则定义、嵌套结构验证和自定义错误消息
package validator如果包本身比较复杂，或者你不想把总说明塞进业务文件里，比较常见的做法是单独建立一个 doc.go 文件来承载包注释。这样既方便维护，也不会干扰实际实现代码。
函数注释要写清功能和结果
函数注释应该紧贴在函数声明上方，并且以函数名开头。对于导出的函数，读者通常最关心三件事：它做什么、接收什么、返回什么。注释不一定要写成长文，但至少要把这三个点交代清楚。
// ParseRequest 解析客户端请求数据
// 支持JSON和表单格式，返回结构化对象
//
// 参数r: HTTP请求对象
// 返回值: 解析后的数据对象和错误信息
func ParseRequest(r *http.Request) (*RequestData, error) {
// 函数实现...
}还有一个容易忽略的规则：只有导出的标识符，也就是以大写字母开头的函数、类型、变量、常量等，才会出现在生成后的文档里。换句话说，内部辅助函数的注释再完整，也不会成为公开 API 文档的一部分。
所以在实际项目里，优先级应该很明确：先确保所有导出 API 都有可读注释，再考虑是否需要给关键内部实现补说明。
让文档更好用的写法：示例、段落和弃用提示
示例代码往往比长解释更有效
对于稍微复杂一点的 API，最能帮助读者上手的，通常不是一大段描述，而是一段能运行、能看输出的示例代码。Go 在这方面支持得很好：示例函数可以直接被文档工具识别。
示例通常放在 <包名>_test.go 文件中，函数名以 Example 开头：
// ExampleParseRequest 展示如何解析POST请求
func ExampleParseRequest() {
req := &http.Request{/* 模拟请求 */}
data, _ := ParseRequest(req)
fmt.Println(data.ID)
// Output: 123
}命名也有约定可循：ExampleFuncName 对应普通函数，ExampleType_Method 对应某个类型的方法。如果同一个 API 需要多个示例，可以继续使用 ExampleFuncName_1、ExampleFuncName_2 这样的后缀。
这类示例的价值在于，它不只是“给人看”，往往还能作为行为说明，帮助团队成员快速确认一个 API 的预期用法。
用空行和缩进把注释写出层次
Go 注释虽然不依赖特殊标记，但并不等于只能写成一整段文字。注释中的空行会被视为新段落，适合用来拆分说明、规则和示例。需要展示代码块时，按约定缩进即可。
// IntsElem 用于安全地从int切片读取元素
//
// 根据参数index可以有几种情况：
//
// - 零值：取切片的第一个值
// - 正值：从切片0位置开始
// - 负值：逆序从切片最后一个值开始
//
// 例子：
//
// sli := []int{0, -1, -2, -3}
// val, idx := IntsElem(sli, -2)
//
// 返回 val = -2, idx = 2
func IntsElem(ints []int, index int) (value, actualIndex int) {
// 函数实现...
}这种写法的关键不在“排版好看”，而在于读者能更快扫到重点：输入规则、特殊情况、使用例子、返回结果，各自独立，不会挤在一句话里。
弃用 API 要明确标出来
当某个函数或类型已经不再推荐使用时，最稳妥的做法不是悄悄保留，而是在注释里直接使用 Deprecated: 标记。这样文档中会出现明显提示，帮助调用方尽快迁移。
// Deprecated: ElemAt 这个函数已弃用，请使用 IntsElem 函数代替
func ElemAt(ints []int, index int) int {
// 函数实现...
}这里最好顺手写清替代方案，比如“请使用哪个新函数代替”。只写“已弃用”而不告诉读者下一步怎么做，实际帮助很有限。
提交前先预览：本地查看文档效果的方法
注释写得是否清楚，单靠源码视角不一定看得出来。比较实用的习惯，是在提交前先把文档页面跑起来，看标题、段落、示例和 API 入口是否都符合预期。
使用 pkgsite 预览
如果你想接近 pkg.go.dev 的浏览体验，可以直接使用 pkgsite：
go install golang.org/x/pkgsite/cmd/pkgsite@latest
cd 你的项目目录
pkgsite -http=:6060启动后，在浏览器访问本地的 http://localhost:6060 就可以查看文档页面。对于需要检查包概览、导出符号结构、示例展示效果的场景，这种方式通常更直观。
使用 godoc 命令
如果你的环境里已经有 godoc，也可以直接启动本地服务：
godoc -http=:6060 -goroot=$(pwd)然后访问 http://localhost:6060/pkg/ 查看项目文档。这种方式足够轻量，适合快速检查注释是否被正确识别。
无论使用哪种方式，本地预览的重点都一样：确认包说明是否完整、导出 API 是否覆盖、段落是否清晰、示例是否真正解释了用法。
写给团队协作看的几条实践建议
把注释写进工作流，比事后补救更有效。下面几条做法，基本适用于大多数 Go 项目：
- 及时更新：代码行为一旦变化，注释也要同步修改，避免接口已经变了、文档还停在旧版本。
- 保持简洁：注释应该简洁但完整，优先解释调用者需要知道的事实，而不是重复函数名本身。
- 给复杂 API 配示例：当参数组合、边界条件或返回结果不够直观时，示例代码通常比长段落更有效。
- 覆盖所有导出 API：不要让公开接口在文档里留下空白，这会直接抬高使用成本。
- 让代码本身也可读：注释不能替代命名和结构设计，好的代码和好的注释应当互相支撑。
对 Go 项目来说，文档从来不是独立于代码之外的附属品。你写下的每一段导出注释，都会直接影响包在团队内部、开源社区或未来自己眼中的可用性。
如果把 godoc 的规则用顺手了，维护文档这件事反而会变轻：不是多做一份工作，而是在定义 API 的同时，把意图写清楚。对协作、复用和后续维护，这笔投入通常都很划算。
