godoc文档不显示主因是注释格式或位置错误：包注释须顶格写在package声明正上方、无空行、用//开头且以“Package <name>”开头并以英文句号结尾；导出函数注释须紧贴标识符正上方、无空行、首句为完整句子；结构体导出字段注释影响文档生成与校验提示；Deprecated注释需严格满足顶格、单行、冒号后空格且紧邻导出项；使用Go modules时需加-path=.参数。
godoc 文档不显示，90% 是因为注释位置或格式错了一处——不是写得不够多，而是没贴住解析规则的边线。
包注释为什么在 godoc 里完全消失
包注释必须顶格写在 package 声明正上方，且中间**不能有任何空行**，连 <p> 这种 HTML 空段落等效符号都不行。它还必须是 // 开头的单行注释，/* */ 直接被忽略。
- // Package utils 提供字符串和时间工具函数。必须以
Package <name>开头，结尾用英文句号 - 一个包只在一个
.go文件里写包注释，其他文件留空；重复写反而可能因格式不一致导致解析失败 - 如果项目用了 Go modules 且不在
$GOPATH下，godoc -http=:6060默认看不到你的包，必须加-path=.
导出函数注释不生效的三个硬性条件
godoc 只认紧贴导出标识符（首字母大写）正上方、无空行、用 // 写的注释。缺一不可。
- 注释和
func Foo()之间不能插变量、空行、甚至import—— 中间哪怕多一个var cacheSize = 1024，注释就失效 - 首句必须是完整句子，以函数名开头，例如
// TrimSpaceLeft removes leading whitespace.，不能是// removes...或// TrimSpaceLeft: removes...（冒号后少空格会被当标题截断） - 参数说明用
// - s: input string这类社区约定格式，godoc 不解析，但 IDE 悬停会原样显示，建议保持统一
结构体字段注释不是可选，而是强制约束项
导出字段（如 Name string）的注释直接影响 JSON 序列化提示、validator 错误信息、API 文档生成。未导出字段（name string）注释再详细，godoc 也完全无视。
立即学习“go语言免费学习笔记（深入）”；
- 每个导出字段都应有注释，说明业务含义 + 约束，比如
// Email is the verified primary contact address. Required. json:"email" validate:"required,email" - 避免模糊表述：
// user email不如// Email must be RFC5322-compliant and verified during signup. - 字段注释不参与文档生成？错——它出现在 godoc 字段列表里，且 validator 的错误提示直接取这里的内容
Deprecated 注释为什么没标灰、也没悬停提示
// Deprecated: 必须满足三个条件才触发 IDE 标灰和悬停提示：单行、顶格、冒号后空一格，且与导出标识符之间无空行。
- ✅ 正确：
// Deprecated: Use NewClient instead.紧贴func OldClient()上方 - ❌ 错误：
// deprecated: Use NewClient instead.（小写 d）、// Deprecated:Use NewClient instead.（冒号后没空格）、或中间夹了空行 - 注意：该注释只对导出标识符有效；
func oldClient()即使写了也不会被识别
最容易被忽略的是路径和导出耦合：你写了规范注释，但 godoc -http=:6060 启动时没加 -path=.，或者函数名是小写，那注释就真的只是“写给人看”的普通注释，不会进任何文档系统。
