高质量Go框架文档需从首次导出函数起同步编写，godoc注释须紧贴符号、首句为完整句子，每个公开API必须配Example函数，且CI须验证注释无占位符、示例通过、错误场景全覆盖。
高质量的 Go 框架文档不是“写完再补”，而是从第一次导出公开函数时就该同步落地——否则后续补全成本会指数级上升，且极易遗漏边界行为和错误路径。
godoc 注释必须紧贴导出符号，且首行是完整句子
Go 的 godoc 工具只抓取紧邻导出类型、函数、方法上方的连续注释块，中间不能有空行。首句必须是独立、可读的完整陈述，不能是短语或待续句。
- ❌ 错误写法：
// NewRouter creates a new mux router（首句是动词开头的碎片） - ✅ 正确写法：
// NewRouter returns a new *mux.Router configured with default middleware and route matching. - 参数和返回值不强制用
@param，但必须在注释中自然说明，例如：// NewRouter accepts an optional Config struct to tune behavior. - 如果函数可能 panic，必须明确写出：
// Panics if the provided config contains invalid regex patterns.
每个公开函数/类型都需配套 Example 函数
godoc 会自动识别名为 Example<name></name> 的测试函数并渲染为可运行示例。它不是可选装饰，而是文档可信度的底线——没 Example 的 API，用户第一反应是“这玩意真能用？”
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 示例函数名必须严格匹配，比如
type Router struct{}对应func ExampleRouter() { ... } - 示例里不能用
_忽略错误，必须显式检查：if err != nil { log.Fatal(err) } - 示例末尾必须加
// Output: ...行，否则godoc不显示输出；内容要真实，不能伪造 - 避免“玩具示例”：不要只调
NewRouter()就结束，至少演示一次路由注册 + 请求模拟
避免文档与代码脱节的三个硬约束
文档失效往往不是因为没人写，而是没人验证。以下三点必须写进 CI 或本地 pre-commit 钩子：
立即学习“go语言免费学习笔记（深入）”；
- 运行
go doc -all ./... | grep -q "TODO\|FIXME\|UNIMPLEMENTED"，禁止注释里留占位符 - 执行
go test -run=Example -v，确保所有 Example 函数通过且输出稳定 - 对每个导出符号，检查其 godoc 输出是否包含至少一个参数说明和一个错误场景描述（哪怕只是
// Returns io.EOF when the stream ends.）
最常被忽略的是错误传播链的文档覆盖——比如 Router.ServeHTTP 调用了内部 handler，但 handler 的错误未在顶层函数注释中声明。这种断层会让使用者在生产环境遭遇未知 panic 后，翻遍文档也找不到依据。
