godoc已基本弃用，应改用go doc查本地文档、pkg.go.dev托管公开文档；生成静态HTML需选docgen（原生注释）或swag（OpenAPI规范），注释格式和CI部署细节直接影响文档质量。
godoc 已基本弃用，别再为它配环境、调参数、修路径——你生成的不是文档，是幻觉。
go doc 是你现在该用的本地查文档命令
go doc 是 Go 1.13+ 内置命令，不启动服务、不生成文件、不依赖 GOPATH，直接读当前模块源码。它只做一件事：快速告诉你某个导出符号是什么。
- 查包：
go doc net/http（输出纯文本，无跳转） - 查函数：
go doc time.Now（注意包名小写、函数首字母大写） - 查方法：
go doc strings.Reader.Read - 加
-all可看未导出项（仅调试用，go doc -all fmt），但生产文档不该包含它
它不生成 HTML，也不托管；它就是终端里的一次 Enter。如果你需要“打开浏览器看结构化文档”，这不是 go doc 的职责。
想生成可部署的静态 HTML？用 docgen，不是 godoc
godoc -http 在 Go 1.13 后已从安装包移除，手动编译安装的版本在模块项目中行为不可靠，且默认不扫描非 $GOROOT/$GOPATH 路径——哪怕你加了 -path=.，也常因模块嵌套、多 go.mod 或 vendor 干扰而漏包。
立即学习“go语言免费学习笔记（深入）”；
- 正确选择：
github.com/robertkrimen/docgen，轻量、无依赖、只读源码、支持 Go modules - 生成命令：
docgen -output docs/ ./（当前目录需有go.mod） - 它只提取
//行注释，忽略/* */；注释必须紧贴声明上方，中间不能有空行 - 导出标识符（首字母大写）才被收录：
ParseURL可见，parseURL不会出现在任何输出里
别指望 docgen 理解业务逻辑或自动生成请求示例——它只是把你的注释按包组织成 HTML，和 go doc 的语义一致，但可存档、可 CI 部署。
REST API 文档？swag 才是正解，godoc 完全不适用
HTTP handler、请求体、响应状态码、参数位置（path/query/body）——这些信息 godoc 和 docgen 都不关心，它们只管 Go 类型系统。要生成 OpenAPI 规范的 API 文档，必须用 swag。
- 安装：
go install github.com/swaggo/swag/cmd/swag@latest（不是go get） - 前提：handler 函数前必须有完整注释块，如
// @Summary Get user by ID，且中间不能有空行 - 结构体字段必须带
json:tag，否则不会出现在请求/响应示例中 -
swag init必须在项目根目录（含main.go或server.go）运行，否则找不到 handler - 引用类型必须带包名：
{object} model.User✅，{object} User❌
swag 不解析自然语言描述，不猜测字段含义，不兼容 godoc 注释风格。混用两种注释只会让文档残缺或构建失败。
注释写错，等于没写
所有工具都卡在同一个地方：注释位置和格式。哪怕逻辑完美，只要错一处，整段就消失。
- 包注释必须在
package xxx上方，且是该文件唯一包声明前的注释 - 函数注释必须紧贴
func行上方，中间零空行、零缩进偏差 - 首句必须是完整句子，会被提取为摘要；后续空行分段，但第二段不能缩进
- 跨包引用要写全限定名：
See http.NewRequest✅，See NewRequest❌（除非同包）
最容易被忽略的是：你写的注释，工具根本看不到——不是因为路径配错，而是因为函数名小写了，或者注释前多了个空格，或者用了 /* */。先用 go doc 验证能否查到，再谈生成。
