go函数doc注释必须紧贴导出函数正上方无空行，首句以函数名开头+空格+英文句号结尾，参数返回值需用自然语言说明语义而非签名，example函数须在_test.go中且严格匹配命名、签名和// output:格式。
函数 Doc 注释必须紧贴声明正上方，中间不能有空行
go doc 和 IDE 悬停只识别紧贴导出函数（首字母大写）正上方的 // 注释块。只要中间插了空行、变量声明、甚至一个 import，整个注释就失效。
-
func Login(...)前面如果隔了一行空行，// Login handles...就不会出现在go doc输出里 - 不能用
/* */写函数文档——哪怕它物理位置对，godoc直接跳过 - 多个
//行可以连写，但必须连续；断开即终止文档关联
首句必须以函数名开头 + 空格 + 完整英文句子，结尾带句号
这不是风格偏好，是解析器硬性规则：godoc 只把以函数名起始、带空格、结尾有英文句号的首行当作摘要。写错就丢摘要，只剩后续说明。
- ✅ 正确：
// Login handles user login request. - ❌ 错误：
// login handles...（小写）、// Login: handles...（冒号后没空格）、// Login handles（缺句号） - 别写“本函数用于……”，直接说它做什么；调用方不关心“本”，只关心“Login 干什么”
参数、返回值、错误要用自然语言说明语义，不是罗列签名
签名本身由代码定义，注释要补的是代码无法表达的约束和意图。比如 error 类型字段，得明确写出可能的自定义错误变量名。
- 不要写：
// - s: input string（godoc不解析这种格式，纯靠人肉读） - 应该写：
// It validates credentials and returns a session token.// Returns ErrInvalidCredentials if username/password mismatch. - 如果函数返回
error，列出具体错误变量（如ErrNotFound），方便调用方用errors.Is(err, ErrNotFound)判断
Example 函数必须定义在 _test.go 文件里，且末尾有精确匹配的 // Output:
ExampleXXX 是唯一能被 go doc 渲染为可执行示例的机制，但它极其脆弱：名字、位置、签名、输出标记，四者缺一不可。
- 函数名必须是
Example开头 + 驼峰标识符，如ExampleLogin或ExampleUser_GetName - 必须定义在
*_test.go文件中，且与被演示的包同名（不能跨包） - 签名严格为
func ExampleXXX()（无参数、无返回值） - 末尾必须顶格写
// Output:，其后每一行输出必须和fmt.Println实际结果**逐字一致**（包括空格、换行）
真正容易被忽略的是：注释一旦写进代码，就跟函数签名一样需要同步维护。函数加了新参数但注释没提，比没注释更危险——它会稳定地误导人。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
