Go文档注释必须紧贴声明上方且无空行，包级文档需在doc.go中并含package声明，导出符号注释须大写开头、句号结尾。
Go 文档注释必须紧贴函数/类型声明上方
Go 的 godoc 和 VS Code 插件（如 Go extension）只识别紧邻声明前的连续块注释，中间不能有空行或其它语句。写在函数体里、声明后、或者用 // 单行注释起头，都不会被解析为文档。
- ✅ 正确：
// GetUserByID retrieves a user by ID from the database. // It returns nil and an error if not found or on DB failure. func GetUserByID(id int) (*User, error) { ... } - ❌ 错误：
func GetUserByID(id int) (*User, error) { // This comment won't show up in godoc. ... } - ❌ 错误：
/* * Multi-line comment with blank line after. */ <p>func GetUserByID(id int) (*User, error) { ... }（空行打断了关联）
包级文档要放在 doc.go 里，且必须含 package 声明
想让整个模块在 pkg.go.dev 或本地 godoc -http=:6060 中显示简介、使用示例和导出项概览，必须新建一个 doc.go 文件，且第一行必须是 package xxx（与模块名一致），再紧跟注释块。
- 文件路径：模块根目录下（即
go.mod所在目录），文件名必须是doc.go - 注释内容建议包含：模块用途、典型用法、关键导出类型/函数的简要说明
- 不加
package声明，godoc会忽略该文件；命名为README.go或docs.go也无效 - 示例：
// Package user provides user management logic. // // Example usage: // // u, err := user.GetUserByID(123) // if err != nil { // log.Fatal(err) // } // fmt.Println(u.Name) package user
导出符号的文档要以大写字母开头，避免歧义
Go 要求所有导出（public）标识符的文档首句必须是完整句子，且以大写字母开头、以句号结尾。否则 godoc 会把首句当作摘要提取，但格式错误会导致摘要截断或渲染异常。
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
- ✅ 推荐：
// NewClient creates a new HTTP client with default timeout and retry. - ❌ 常见问题：
// newClient creates...（小写开头 → 不被识别为摘要）、// Creates a new HTTP client（缺主语、无句号 → 摘要不完整） - 注意：非导出符号（小写开头的函数/字段）即使写了注释，也不会出现在生成文档中
- 如果函数签名复杂（如带多个返回值），可在注释中用
// Returns: ...显式说明，但不是必须
运行 godoc 本地预览时，工作目录决定可见范围
执行 godoc -http=:6060 后，访问 http://localhost:6060 看到的文档范围取决于你启动命令时所在的目录 —— 它只索引当前目录及其子目录下的 Go 包，不会自动扫描整个 GOPATH 或 module path。
- 想查看自己模块的文档：cd 到模块根目录（含
go.mod），再运行godoc -http=:6060 - 若模块未发布到公网，
pkg.go.dev不会收录；本地godoc是唯一快速验证方式 - VS Code 中 hover 提示依赖
gopls，它默认读取源码注释，但要求注释格式合规，否则提示为空白或仅显示签名 - CI 中可加检查：
go list -f '{{.Doc}}' ./... | grep -q '^$' && echo "missing docs"（粗略检测空文档）
文档能被正确解析的前提是结构合规，而不是字数多少。最容易被忽略的是 doc.go 的命名和包声明，以及函数注释与声明之间有没有空行 —— 这两点一错，整个包的文档就“消失”了。
