go doc 注释不生效主因是空行或格式错误：包注释须顶格写于package声明正上方、无空行、以“package ”开头并以英文句号结尾；func/type注释须紧贴导出标识符正上方、无空行、首句完整且大小写匹配；字段注释需逐行独立、说明业务含义；deprecated注释须严格满足顶格、单行、冒号后一空格等条件。
Go Doc 注释不生效，90% 是因为注释和代码之间“隔了一行空行”或“拼写没对齐”——不是写得少，而是贴得不够紧。
包注释为什么在 go doc 里完全消失
包注释必须顶格写在 package 声明正上方，中间不能有任何空行（包括 HTML 段落、空白符、甚至 <p></p> 这类等效空行），且只能是 // 开头的单行注释。
-
// Package utils必须以Package <name></name>开头，结尾用英文句号，比如// Package utils provides string and time utilities. - 一个包只允许在一个
.go文件里写包注释；其他文件留空，重复写反而可能因格式不一致导致解析失败 - 如果项目用了 Go modules 且不在
$GOPATH下，godoc -http=:6060默认看不到你的包，必须加-path=.参数 -
/* */包注释、首句漏句号、用了全角标点（如“。”）、包名大小写不匹配（如写成Utils但实际包名是utils），都会让整个包文档消失
func 和 type 的 Doc 注释为何不被识别
godoc 只认紧贴导出标识符（首字母大写）正上方、无空行、用 // 写的注释。缺一不可。
- 注释和
func Foo()之间不能插任何东西：空行、变量声明（如var cacheSize = 1024）、import、甚至另一个注释块 - 首句必须是完整句子，以函数/类型名开头 + 空格，结尾带英文句号，例如
// Login handles user login request.，不能是// login handles...（小写）、// Login: handles...（冒号后少空格）、// Login handles（缺句号） - 后续行可补充参数、返回值、错误条件，但不要用 Markdown；
go doc不渲染，但 IDE 悬停会原样显示 - 如果函数签名改了（比如加了新参数），注释里没同步更新，就比没注释更危险——它会误导调用方
结构体字段注释不是可选，而是强制约束项
导出字段（如 ID int）的注释直接影响 go vet 检查、IDE 悬停提示、validator 错误信息，以及 API 文档生成。
- 每个导出字段都必须有独立的
//行注释，不能合并写成// ID int // Name string - 注释要说明业务含义 + 约束，比如
// Email is the verified primary contact address. Required. json:"email" validate:"required,email"，而不是模糊的// user email - 未导出字段（如
id int）即使写了注释，go doc也完全无视；但内部逻辑仍可用//解释“为什么”，比如并发安全假设 - 字段之间不能有空行，否则后一个字段注释会被视为前一个字段的延续（
gopls解析异常）
// Deprecated: 注释为什么没标灰也没悬停提示
// Deprecated: 要触发 IDE 标灰和悬停提示，必须同时满足三个硬性条件：顶格、单行、冒号后空一格，且与导出标识符之间无空行。
- 必须是
// Deprecated:（D 大写，冒号后紧跟一个空格），不能是// deprecated:、// DEPRECATED:或// Deprecated :（空格位置错） - 必须单独成行，不能和其他注释混在同一行，也不能后面跟换行再写说明（
// Deprecated: Use NewClient instead.\n// This will be removed in v2.0.中第二行不会被识别为弃用提示） - 必须紧贴导出标识符，中间不能有空行；如果该标识符本身没导出（小写开头），
// Deprecated:完全无效 - 弃用说明建议写清替代方案，比如
// Deprecated: Use NewClient instead.，而不是含糊的// This is old.
最常被忽略的是“空行”和“大小写一致性”——哪怕多一个看不见的空格、少一个英文句号、或者把 Package utils 写成 package utils，整个注释块就会从 go doc 输出里消失。工具链不猜意图，只按规则硬匹配。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
