Go文档注释必须以//开头紧贴声明上方，仅识别导出标识符，且需位于GOROOT/GOPATH或显式-path路径下；跨包引用须用全限定名。
Go 文档注释必须以 // 开头且紧贴函数/类型声明上方
Go 的文档系统不识别 /* */ 块注释，也不接受空行隔开。哪怕只多一个空行，godoc 就会完全忽略该注释。
- ✅ 正确：
// ParseURL parses a URL string and returns a *url.URL.<br>func ParseURL(s string) (*url.URL, error) { ... } - ❌ 错误：
/**<br> * ParseURL parses a URL string...<br> */<br>func ParseURL(...) { ... }（godoc不解析） - ❌ 错误：
// ParseURL parses a URL string...<br><br>func ParseURL(...) { ... }（中间空行导致断连）
godoc 默认只扫描 $GOROOT/src 和 $GOPATH/src 下的包
你的项目如果在 ~/projects/myapp 这类非标准路径，godoc -http=:6060 启动后根本看不到它——除非显式指定 -goroot 或用 -path。
- 本地开发时快速预览：运行
godoc -http=:6060 -path=.（当前目录需含go.mod或package声明） - 若项目用了 Go modules 且不在
$GOPATH，-goroot无效，必须用-path -
godoc不支持嵌套模块自动发现；子模块要单独加-path或整合进主模块的doc.go
导出标识符（首字母大写）才被 godoc 收录
小写字母开头的函数、字段、常量，无论有没有注释，都不会出现在生成的文档里——这是 Go 的导出规则，不是文档工具缺陷。
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 想让某个内部 helper 函数可查？不行。改名
Helper是唯一办法，但违背封装意图 - 结构体字段
name string永远不会显示；必须是Name string才能出现在字段列表中 -
const maxRetries = 3不会被索引；得写成const MaxRetries = 3并配注释
跨包引用要写全限定名，否则 godoc 不做链接
注释里写 See ParseURL，不会变成跳转链接；必须写成 See url.ParseURL（假设在 net/url 包里），且目标包已被 godoc 加载。
立即学习“go语言免费学习笔记（深入）”；
- 同一包内函数可简写：
See ParseURL→ 自动链接到本包的ParseURL - 跨包必须带包名前缀：
See http.NewRequest、See io.Copy - 别写
See the ParseURL function这类自然语言描述；godoc只认Package.Func或Func格式 - 如果引用的包没被加载（比如未在
-path中），链接失效且无提示
最常被忽略的是路径和导出规则的耦合：你以为写了注释就万事大吉，其实 godoc 看不到它，可能只是因为函数名小写了，或者项目不在它默认扫描范围内。
