Go 包文档该写在哪儿才被 go doc 和 VS Code 正确识别
Go 不认 README.md 作为包文档——哪怕你写得再漂亮，go doc、godoc（或新版 go doc 命令）和大多数 IDE 都不会把它当包说明。真正起效的只有源码文件顶部的注释块。
- 必须是紧贴
package声明上方的「顶级注释块」，且中间不能空行 - 注释必须是
//开头的普通注释，不是/* */块注释（后者会被忽略） - 如果包有多个
.go文件，只有一份注释生效：按字典序第一个含包注释的文件胜出 - 别在
main包里写长文档——go doc对main包支持弱，优先用 CLI help 或独立文档
包注释里哪些内容会被 go doc 渲染成摘要
第一段（直到第一个空行或代码块前）会被提取为包摘要，在 go doc -q mypkg 或 IDE 悬停时显示。这段话要够短、够直给，别塞参数说明或安装步骤。
- 避免用 Markdown 语法：
**加粗、[链接]全部失效，纯文本渲染 - 函数名、类型名想高亮？得用
`funcName`这种反引号包裹，否则就是普通单词 - 空行分隔很重要：第一段之后的空行以下内容，会原样保留在完整文档页，但不进摘要
- 别写「本包用于…」——直接说「
HTTPTransport实现带超时控制的 HTTP 客户端」更有效
README.md 在 Go 项目里到底该放什么
README.md 不是包文档，而是给人看的「项目入口说明书」。它的价值不在被工具解析，而在降低新用户启动门槛。
- 放真实可运行的快速上手示例，比如
go run ./cmd/example，而不是抽象接口描述 - 列清楚依赖约束：
go 1.21+、是否需cgo、外部服务（Redis / Postgres）如何配 - CI 状态、测试覆盖率 badge 可以加，但别堆砌无关徽章；贡献指南写具体点，比如「PR 必须含测试+更新 CHANGELOG」
- 别把 godoc 里的 API 列表复制进来——维护两份只会过期，README 里只留最常用 2–3 个函数调用示意
跨平台查看文档时容易漏掉的细节
go doc 默认只查本地已安装的包；如果你用的是模块路径（如 github.com/user/repo/pkg），没 go get 过就查不到——这不是文档写得不对，是环境没加载。
立即学习“go语言免费学习笔记（深入）”；
- 本地开发时，用
go doc -http=:6060启服务，浏览器打开就能看全量渲染效果，比终端更准 - VS Code 的 Go 扩展依赖
gopls，而gopls默认只索引当前 module；如果包在replace路径下，得确认go.work或replace已生效 - 私有仓库的包文档在公司内网能查，推到 GitHub 后别人看不到？检查
go.mod里模块路径是否暴露了内部域名（如git.internal.company/pkg）
包注释的换行、缩进、空行位置，看着琐碎，但改错一行，go doc 就可能完全不显示摘要——这种地方没报错，只默默失效。
