Go项目生成接口文档应弃用godoc，改用go doc查本地文档、pkg.go.dev托管公开文档；生成静态HTML需选docgen（原生注释）或swag（OpenAPI规范），注释格式和CI部署细节影响文档质量。
Go 项目要生成可用的接口文档，godoc 命令本身已基本弃用（自 Go 1.13 起不再随 Go 安装包默认提供），直接运行 godoc -http=:6060 会报错或无响应；现在标准做法是用 go doc 查看本地文档，用 pkg.go.dev 托管公开文档，而生成静态 HTML 文档需借助第三方工具。
用 go doc 快速查本地接口说明
go doc 是 Go 1.13+ 内置命令，替代了旧版 godoc 的本地查看功能，不启动服务、不生成文件，但能即时显示导出符号的文档注释。
- 查看某个包：运行
go doc fmt或go doc net/http - 查看某个函数：如
go doc time.Now（注意包名小写，函数首字母大写） - 查看某个方法：如
go doc strings.Reader.Read - 加
-all可显示未导出项（调试用），但生产文档不应依赖它 - 输出是纯文本，不支持跳转、搜索或导出 HTML —— 它只是“看”，不是“生成”
生成可部署的静态 HTML 文档：用 docgen 或 swag？
真正需要生成带导航、可托管的 HTML 接口文档时，godoc 已不适用。主流选择有两个方向：
- 面向 Go 原生代码注释（
//开头的包/函数说明）：用github.com/robertkrimen/docgen（轻量、无依赖、只读源码） - 面向 REST API 接口定义：用
swag（即swaggo/swag），需在代码中写// @Summary等 Swagger 注释，生成的是 OpenAPI + HTML -
docgen示例：docgen -output docs/ ./...，会扫描当前模块所有包，生成index.html和按包组织的 HTML 文件 -
swag init不解析普通注释，只认@开头的 Swagger 标签；如果项目没有 HTTP handler 层或不用 OpenAPI 规范，别硬套swag - 二者不兼容：
docgen不能识别@Param，swag也不解析// Implements io.Reader这类自然语言描述
注释格式直接影响文档质量
无论用 docgen 还是 go doc，都只提取以 // 开头、紧贴声明上方的注释块，且对空行和缩进敏感。
Golang Samber Hot
下载
在 Golang 中使用 samber/hot 进行内存缓存，支持 LRU、LFU、TinyLFU、W‑TinyLFU、S3FIFO、ARC、TwoQueue、SIEVE、FIFO 等淘汰算法，提供 TTL、缓存加载器及分片功能。
立即学习“go语言免费学习笔记（深入）”；
- 正确写法：
// Reader reads from an underlying byte slice.紧跟type Reader struct { ... }上方，无空行 - 错误写法：注释前有空行、缩进不一致、混用
/* */（go doc完全忽略块注释） - 函数参数和返回值无需单独注释；但若类型不直观（如
func Parse(s string) (int, error)），应在函数注释里说明 “returns -1 on invalid input” - 包级注释必须放在
package xxx上方，且是该文件唯一包注释；多个文件的包注释会被合并，取第一个非空的 - 导出标识符（首字母大写）才被收录；
newReader不会出现在文档里，哪怕它有完整注释
CI 中自动生成并推送文档的常见陷阱
想在 GitHub Actions 里跑完 docgen 后自动推到 gh-pages 分支？这些点容易卡住：
-
docgen默认不包含go.mod信息，生成的页面顶部不会显示模块路径；需手动在-title参数里指定，如-title "example.com/mylib v0.3.0" - 如果项目用了 replace 或 indirect 依赖，
docgen ./...可能因 import path 解析失败而中断；建议先go mod tidy并确保go list ./...能正常执行 - 生成的 HTML 里所有链接都是相对路径，部署到子路径（如
https://a.com/lib/docs/）时会 404；docgen不支持--baseurl，得用sed或构建脚本批量修正href和src - GitHub Pages 默认不渲染
index.html在子目录下，需确认仓库设置里的 “GitHub Pages source” 指向正确的分支和文件夹（如/docs）
真正难的不是生成那几页 HTML，而是让每个导出函数的注释都准确反映行为边界、panic 条件和并发安全性——这些内容不会被任何工具自动补全。
