go doc 不支持直接解析 markdown 文档，需通过 go:generate 生成 markdown 片段并用 mdbook 整合，或提取文档中 `go 代码块执行测试验证一致性。
用 go doc 直接看 Markdown 格式的函数说明？不行
Go 官方工具链不解析 Markdown，go doc 只读取源码注释里的纯文本（支持简单标记如 // 后的 *list 或 **bold**，但不渲染 .md 文件）。想让 Markdown 文档和代码联动，得绕过 go doc，走外部工具链。
- 典型错误现象：
go doc pkg.Func显示空白或只有签名，实际文档写在doc/func.md里 - 真实使用场景：团队用 Markdown 写 API 说明、CLI 参数手册、示例流程，希望和
go build或 CI 绑定，避免文档和代码脱节 - 关键限制：Go 没有内置 “文档源 → HTML/PDF/CLI help” 的 pipeline，必须自己搭
推荐方案：用 mdbook + go:generate 同步代码注释到 Markdown
不是把 Markdown 转成 Go 能读的东西，而是让 Go 代码“吐出” Markdown 片段，再由 mdbook 整合成完整文档站。这样文档永远和最新代码一致。
-
go:generate脚本可调用自定义工具（比如用go doc -json提取结构化信息，再用text/template渲染成 .md） - 示例生成命令：
//go:generate go run gen-docs.go -o docs/api/bytes.md - 注意路径问题：
go:generate在当前包目录执行，-o路径需写相对或绝对，否则生成文件可能错位 -
mdbook serve实时预览，但默认不监听.go文件变化——要手动touch docs/README.md或用entr触发重载
如果坚持用 Markdown 写文档，怎么让 go test 验证它没过时？
文档驱动开发的核心不是“写完 Markdown 就算数”，而是让文档成为测试用例的一部分。最直接的方式：把文档里的代码块提取出来，作为可执行测试。
- 用
blackfriday或goldmark解析 Markdown，匹配```go块，写入临时.go文件，再调用go run或go test - 常见坑：
```go里漏了package main或func main()，导致go run失败；建议统一要求示例含完整可运行结构 - 性能影响：每跑一次测试都要解析全部文档，建议只对修改过的 .md 文件做验证（可用
git diff --name-only过滤） - 兼容性：Go 1.21+ 支持
//go:embed，但嵌入 Markdown 后仍需额外解析——别指望靠 embed 自动绑定逻辑
godoc 已废弃，但自建文档服务仍要小心 GOPATH 和模块路径
现在用 golang.org/x/tools/cmd/godoc 本地起服务已不推荐，但若你真要用（比如离线环境），GOPATH 和 GO111MODULE=off 会彻底破坏模块感知，导致找不到依赖包的文档。
立即学习“go语言免费学习笔记（深入）”；
- 正确做法：用
pkg.go.dev的本地镜像方案（如ghcr.io/golang/docserver），或直接用mdbook+go list -json构建索引 - 容易被忽略的点：
go list -m all输出的模块路径可能带+incompatible，文档生成脚本若硬编码路径前缀，会导致链接 404 - CI 中常见失败：
go mod download没跑全就生成文档，结果引用的第三方包文档缺失——必须确保go mod tidy和go mod download先完成
文档和代码之间没有自动桥接层，所有“同步”都靠脚本粘合。最麻烦的不是写第一个生成器，而是维护它适配新版本 Go 的 go doc -json 输出格式变化。
