pkg.go.dev 通过模块根目录的 README.md 显示模块简介，必须命名为 README.md 且位于 go.mod 同级目录；包文档由紧贴 package 声明上方的连续注释提供，中间不能有空行。
Go 模块本身不支持像 go doc 直接渲染模块级文档（如 github.com/user/repo 主页说明），go doc 和 pkg.go.dev 只索引包（package）而非模块（module）。真正起作用的是根目录的 README.md 和每个包的 Go 注释。
如何让 pkg.go.dev 显示模块简介和链接
pkg.go.dev 会自动抓取模块根目录的 README.md，并将其渲染为模块首页的「Overview」区域。这是唯一能让外部用户第一眼看到模块用途的方式。
- 文件必须叫
README.md（大小写敏感），放在模块根目录（即含go.mod的目录） - 首行建议用一级标题
# mymodule，否则可能被截断或忽略 - 支持标准 Markdown，但不支持 HTML、JS 或自定义样式
- 链接如
[GitHub](https://github.com/you/mymodule)会被正常渲染 - 如果 README 空或不存在，
pkg.go.dev会显示 “No documentation found”
如何给具体包（package）写可被 go doc 解析的注释
每个 .go 文件顶部的包注释（紧贴 package xxx 上方的连续多行注释）会被 go doc 和 pkg.go.dev 提取为该包的文档主体。
- 必须是
/* ... */或//开头的连续块，且与package之间**不能有空行** - 推荐用
//风格：第一行简明概括，后续段落说明用途、典型用法、注意事项 - 函数/类型前的注释同理，但只影响该符号，不影响包级描述
- 注释中可使用
`code`、**bold**（仅 pkg.go.dev 支持）、链接等基础格式
/* Package sqlx extends database/sql with named query support.It lets you write:
立即学习“go语言免费学习笔记（深入）”；
db.Get(&user, "SELECT * FROM users WHERE id = :id", map[string]interface{}{"id": 1})instead of positional args. */ package sqlx
常见踩坑：为什么 go doc 不显示你的注释
最常遇到的不是写得不对，而是位置或格式不满足解析器要求。
- 包注释和
package语句之间有空行 →go doc忽略整段注释 - 用了
/** */但内部混入了非注释内容（如误加fmt.Println）→ 解析中断 - 模块未发布到公开代理（如私有 GitLab），
pkg.go.dev无法抓取 README 或代码 → 只能本地go doc -http=:6060查看 - 运行
go doc（如go doc github.com/gorilla/mux）实际查的是默认包（./），不是模块顶层 → 应该查go doc github.com/gorilla/mux/mux或进项目后go doc
要不要在 go.mod 里写文档
不要。Go 官方明确不支持在 go.mod 中添加注释性字段（如 // Description 或 doc = "..."）。这类内容不会被任何工具识别，还会导致 go mod tidy 自动删掉。
模块元信息（作者、许可证、官网）应通过 README.md 和项目仓库的 .github/FUNDING.yml、LICENSE 等标准文件承载。Go 工具链只认这些约定路径。
