Go注释仅//和/ /两种，但用法严格：导出标识符必须用紧邻上方的//写Doc注释，首句以函数名开头并用Args:/Returns:/Errors:引导；结构体导出字段需注明业务约束与tag；包注释须用/ /置于package前且唯一，首句为“Package xxx”。
Go语言注释只有两种语法形式，但用法差异极大：单行注释 // 是主力，多行注释 /* */ 仅限包说明或临时屏蔽代码——别在函数上用 /* */ 写文档，godoc 不认。
导出函数/方法必须用 // 写 Doc 注释，且紧贴声明上方
这是最常踩的坑：空一行、写在函数后、用 /* */ 包裹，godoc 全部忽略。它只认“紧邻导出标识符正上方”的连续 // 块。
- 首行必须是完整句子，以函数名开头，如：
// Add returns the sum of a and b. - 参数、返回值、错误用
Args:/Returns:/Errors:引导，不换空行 - 别写“本函数用于…”，直接说它“做什么”，比如
// ParseJSON unmarshals raw JSON into v, returning error if malformed.
结构体字段注释要带业务约束，不是重复类型
只写 // Email string 没用；调用方需要知道这个字段能不能为空、是否校验邮箱格式、序列化时用什么 key。
- 导出字段（首字母大写）必须注释，哪怕只有一句：
// Name is the user's full name, required, max 100 chars - 可合并 tag 提示：
// Email is the primary contact address. Required. json:"email" validate:"required,email" - 非导出字段（小写）不用 Doc 注释，但关键逻辑处可用
//解释“为什么”，比如并发安全假设
包注释必须用 /* */ 放在 package 前，且只能一份
多文件包里，只要一个 .go 文件顶部有包注释就行；重复写会污染 godoc 输出，且毫无意义。
立即学习“go语言免费学习笔记（深入）”；
- 第一句必须是
Package xxx开头，如：/* Package http provides HTTP client and server implementations. */ - 超三行建议单独建
doc.go，方便集中维护和加示例代码块（缩进 4 空格自动识别） - 别在每个文件都补一句“本文件实现xxx”，
godoc只取第一个识别到的包注释
真正难的不是语法，而是判断“哪句话值得写进注释”：它得解决调用方的疑问，而不是复述代码。比如 // i++ 后面跟 // increment i 就是噪音；但 // use atomic.StoreUint64 to avoid race on counter 就是关键信息。
