go语言注释需紧邻声明上方无空行，包注释置于 package 语句前用 /…/ 块注释，结构体 字段与方法注释提升 API 可读性，godoc 可本地启动服务实时预览文档。
Go 语言 的注释和文档系统简洁高效，关键在于遵循约定而非依赖复杂语法。只要注释写在正确位置、格式规范，godoc就能自动生成可读性强的文档，甚至支持 Web 查看。
注释必须放在声明上方，且紧邻不空行
Go 只识别“前置式”注释：函数、变量、结构体、方法等的注释必须直接写在它们的上一行，中间不能有空行。否则 godoc 会忽略。
- ✅ 正确写法：
// Add returns the sum of a and b. func Add(a, b int) int {return a + b}- ❌ 错误写法（空行或位置偏移）：
// This comment won't be picked up. func Add(a, b int) int {……} <p>// Also invalid: comment after declaration func Add(a, b int) int {……} // This is too late.包注释写在 package 语句前，用块注释更清晰
每个包应有一个简明扼要的包级说明，放在 package xxx 语句正上方。推荐使用 /* …… */ 块注释，尤其当需要多行描述或强调用途时。
/* Package calculator provides basic arithmetic operations like addition, subtraction, and multiplication. <p>It's designed for educational use and small-scale tools. */ package calculator注意：包注释只需一份，放在任意一个。go文件顶部即可，不需要每个文件都重复。
立即学习“go 语言免费学习笔记（深入）”；
结构体字段和方法也支持注释，提升 API 可读性
导出的结构体字段（首字母大写）如果加了注释，godoc会一并展示；方法同理。这对定义清晰的 接口 非常有用。
// User represents a registered user in the system. type User struct {// Name is the full name of the user. Name string // Age is the age in years; zero means unknown. Age int} <p>// Greet returns a friendly greeting message. func (u User) Greet() string { return "Hello, " + u.Name}用 godoc 本地启动文档服务，实时预览效果
安装后无需额外配置，直接运行命令即可生成本地文档站点：
- 查看当前包文档：
godoc -http=:6060，然后访问 https://www.php.cn/link/ed4e17d67f76e380e297298c8629c38d - 指定模块路径（如在项目根目录）：
godoc -http=:6060 -goroot=. - 终端中快速查某个函数：
godoc fmt Println
确保代码已保存，godoc会自动解析最新内容——改完注释刷新网页就能看到更新。
