goland函数注释需紧贴func声明、无空行、//开头，首句为“函数名+空格”且以英文句号结尾；结构体导出字段须逐行注释；包注释须顶格、严格匹配包名并以英文句号结尾。
GoLand 里函数注释不被 go doc 识别，大概率是空行或首句格式错了
Go 工具链只认紧贴 func 声明正上方、无空行、用 // 开头的单行注释，且首句必须以函数名 + 空格开头、结尾带英文句号。哪怕多一个空格或少一个句号，go doc 和 IDE 悬停都可能直接忽略。
常见错误包括：
-
// Login handles user login→ 缺句号，不被识别 -
// login handles user login.→ 首字母小写，不匹配函数名Login -
// Login: handles user login.→ 冒号后没空格，解析失败 - 注释和
func之间插了空行、变量声明或另一个注释块
实操建议：
- 光标停在函数名上，按
Ctrl+Q看是否弹出文档；没弹出就说明注释没生效 - 别用
/* */写函数文档——go doc完全不认 - 函数签名改了（比如加参数），务必同步更新注释里的
@Param或描述，否则比不写更危险
结构体字段注释必须逐行写，否则 go vet 会报 exported field X should have comment
导出字段（首字母大写）没注释，go vet 或 revive 默认就会警告。这不是风格问题，而是强制约束——它影响 IDE 悬停提示、validator 错误文案、甚至 API 文档生成。
正确写法是每行字段单独配一行 // 注释，说明业务含义，不是类型或 JSON tag：
// User represents a registered account.
type User struct {
// ID is the unique identifier generated by the system.
ID int `json:"id"`
// Name is the display name, max 50 chars.
Name string `json:"name"`
}
容易踩的坑：
- 把多个字段合并在一个注释块里，如
// ID and Name are user fields→ 不通过检查 - 只写
// int或// json:"id"→ 语义缺失，IDE 提示为空 - 未导出字段（小写）也强行加注释 → 无意义，还干扰阅读
包注释只能有一处，且必须顶格写在 package 声明正上方
一个包里写两段 // Package xxx，只有最顶部、紧邻 package 的那一段会被 go doc 解析。其他位置、带空行、缩进、或用了全角标点的，都会导致整个包文档消失。
GoLand 2026.1.1 是 2026.1 发布后的首个维护修正版本，适合已经开始体验 2026.1 新功能并希望同步补丁的开发者。它更适合用于入门项目、现有项目迁移测试和 IDE 行为验证。
正确格式严格限定为：
- 必须是
// Package <name></name>开头（<name></name>与实际包名大小写完全一致） - 结尾必须是英文句号
.，不能是中文“。”或漏掉 - 中间不能有空行，不能有 HTML 标签、
<p></p>或注释分隔线 - 如果项目不在
$GOPATH下，用godoc -http=:6060 -path=.启动才看得见本地包
常见失效场景：
-
package auth上方写了// Package Auth（大写 A）→ 包名是小写，不匹配 - 注释前有
import "fmt"或空行 → 被跳过 - 用了
/* Package auth */→go doc完全无视
用 Goanno 插件自动生成注释时，模板变量要对得上，否则 ${params} 变成乱码
Goanno 默认模板里写 ${params}，但 Goland 实际需要的是 ${PARAMS}（全大写）。如果没改，生成出来就是字面量 ${params}，不是真实参数列表。
配置路径：Settings → Editor → Live Templates → 找到 Normal Method 模板 → 把 ${params} 替成 ${PARAMS}，再把 ${return_types} 改成 ${RETURN_TYPES}。
其他关键点：
- 快捷键是
Ctrl+Alt+/（Windows）或Cmd+Option+/（macOS），不是Ctrl+/ - 模板里用
${function_name}能取到函数名，但拼写必须和代码里完全一致（大小写、下划线） - 如果函数有泛型参数或复杂签名，
${PARAMS}可能截断，这时得手动补全，别盲目依赖
真正省时间的地方不是“一键生成全部”，而是让 ${PARAMS} 和 ${RETURN_TYPES} 正确展开——剩下的描述性文字，还是得你来填。
