Go文档注释必须紧贴声明且禁止空行：包注释须顶格置于package声明正上方，函数/类型注释须紧贴导出标识符正上方，中间不得有空行或/ /块注释，否则go doc无法识别。
文档注释必须紧贴声明，不能有空行
Go 的 go doc 和 godoc 工具只识别「紧邻声明上方」的连续 // 注释。一旦中间插入空行，注释就和下面的函数、类型或包失去关联。
常见错误现象：go doc mypkg.MyFunc 返回 “no documentation found”，但注释明明写了——大概率是注释和 func 之间多了个空行，或者用了 /* */ 块注释。
- 包级注释必须放在
package xxx正上方，且是文件第一个非空非注释块 - 函数/类型/变量注释必须紧贴其声明行，前面不能有空行，也不能被其他语句隔开
- 推荐统一用每行以
//开头的多行风格，避免混用/* */
用 GoLand 自动生成带格式的注释模板
手动敲 // 容易漏掉参数说明或格式不一致。GoLand 提供了快捷生成能力，但需触发位置正确：
- 光标放在函数名、类型名或包声明行上（不是函数体内），按
Alt + Enter - 选择
Generate documentation comment（不是 “Add comment”） - 它会自动补全形参名、返回值占位符，并保持缩进对齐
- 生成后仍需人工填充语义，比如
// s 为 nil 时返回空字符串这类关键行为
注意：该操作不会帮你补包注释，包注释得手写在 package 上方——而且必须是整个文件最顶上。
GoLand 2026.1.1
下载
GoLand 2026.1.1 是 2026.1 发布后的首个维护修正版本，适合已经开始体验 2026.1 新功能并希望同步补丁的开发者。它更适合用于入门项目、现有项目迁移测试和 IDE 行为验证。
go doc 查不到本地包？先确认模块路径是否合法
即使注释全对，go doc 仍可能报 no such package。这不是文档问题，而是导入路径解析失败。
- 确保项目根目录下有
go.mod，且module行声明的路径能被完整导入（例如module github.com/you/project） - 查本地包时，必须用完整导入路径：
go doc github.com/you/project/pkgname，而不是go doc pkgname - 如果包在
internal/下，外部无法导入，go doc也查不到——这是设计限制，不是 bug - IDE 内的 Quick Documentation（
Ctrl+Q）不依赖模块路径，只要文件在项目中就能显示，可用来快速验证注释是否被识别
别依赖 godoc 服务，本地 go doc 就够用
godoc 命令已在 Go 1.16+ 被移除，官方明确推荐用内置 go doc。现在装 golang.org/x/tools/cmd/godoc 属于历史兼容方案，容易因 Go 版本升级失效。
- 查当前包：终端进入包目录，执行
go doc - 查某个符号：如
go doc fmt.Printf或go doc time.Duration.Seconds - 查自定义包：必须确保该包可被
go build成功编译，否则go doc不认 - VS Code 或 GoLand 的悬浮文档（Quick Documentation）底层调用的就是
go doc，所以只要命令行能查到，IDE 里就能看到
真正容易被忽略的是：文档能不能被别人用，取决于他们能否正确导入你的包——而导入路径由 go.mod 决定，不是文件路径。
