Go包文档格式是工具链契约：包注释须顶格写在package前且无空行，首句以包名开头并带句号；导出标识符注释须紧贴声明上方无空行；仅支持//行注释，禁用空行、制表符及Markdown。
Go 包文档不是写给人看的，是写给 godoc 和 IDE 看的——注释格式错一个空行、首句不独立成行、包名没对齐，go doc 就不显示或显示异常。
包注释必须顶格写在 package 声明前，且独占一段
这是最常被忽略的硬性规则。Go 要求包级注释必须是紧邻 package 声明上方的**第一个非空、非注释块**，且与 package 之间**不能有空行**。
错误写法（godoc 完全忽略）：
// 这段注释会被跳过 // 因为上面有空行package utils
正确写法：
立即学习“go语言免费学习笔记（深入）”；
// Package utils 提供通用工具函数，如字符串截断、时间格式化。 // // 注意：所有函数均不修改输入参数，返回新值。 package utils
- 首句必须是完整句子，以包名开头，结尾带句号，单独成行
- 后续说明可换行，但需用空行与首句分隔
- 不能用
/* */块注释；只认//行注释 - 如果包有多个
.go文件，**仅其中一个文件需要写包注释**，其他文件留空即可
导出标识符的注释要直接写在声明上方，无空行
函数、类型、变量等导出名（首字母大写）的文档注释，必须紧贴其声明前，中间不能插空行或其它语句。
错误示例（TrimSpaceLeft 不会出现在 godoc 中）：
// TrimSpaceLeft 移除字符串左侧空白
//
// 支持 \t\r\n 等 Unicode 空格符。
func TrimSpaceLeft(s string) string { ... }
var (
// 缓存最大容量
CacheSize = 1024
)
正确写法：
立即学习“go语言免费学习笔记（深入）”；
// TrimSpaceLeft 移除字符串左侧空白。
//
// 支持 \t\r\n 和 Unicode 标准空白字符（如 U+0085、U+2000–U+200A）。
func TrimSpaceLeft(s string) string { ... }
// CacheSize 是全局缓存的最大条目数。
CacheSize = 1024
- 首句必须是完整句子，结尾带句号，不可省略
- 若函数有参数或返回值需说明，用
// - s: 输入字符串这类格式，但非强制；godoc不解析这种语法，只是约定俗成 - 结构体字段注释写在字段上方，同样不能空行；未导出字段（小写）的注释不会被
godoc采集
go doc 和 gopls 对空行和缩进极其敏感
看似微小的格式偏差，会导致文档在终端、VS Code 悬停提示、godoc 网站中完全失效或显示错乱。
- 包注释后若紧跟空行再写
import，整个包注释即失效 - 导出函数前若有空行、或注释末尾有多余空格，
gopls可能无法触发悬停文档 - 注释中使用制表符（
\t）而非空格缩进，某些godoc版本会渲染异常 -
go doc -all会显示未导出名，但标准go doc和 IDE 只处理导出名 + 正确格式注释
验证方式很简单：
go doc utils go doc utils.TrimSpaceLeft
输出为空？立刻检查注释位置、空行、首句标点。
避免在注释里写代码示例或 Markdown
godoc 不支持 Markdown 渲染，也不执行代码块语法高亮。所谓「示例」只能靠纯文本描述，或配合 example_*.go 文件。
- 不要写
```go或**加粗**—— 这些会原样显示为文字，破坏可读性 - 真正有效的示例必须放在独立文件中，命名形如
example_utils_test.go，且含func ExampleXXX() - 注释中可提「参见 ExampleTrimSpaceLeft」，但不能内联代码
- 链接用纯 URL 即可（如
https://pkg.go.dev/strings#TrimSpace），godoc会自动转为超链接
文档生成不是自由写作，它是 Go 工具链的一环——格式即契约。少一个句号、多一行空格，就等于没写。
