Go 的 godoc 工具默认只生成导出（首字母大写）的标识符文档；未导出的函数、变量或类型不会出现在生成的 HTML 或命令行文档中，无需拆分文件即可实现“选择性文档化”。
go 的 `godoc` 工具默认只生成导出（首字母大写）的标识符文档；未导出的函数、变量或类型不会出现在生成的 html 或命令行文档中，无需拆分文件即可实现“选择性文档化”。
在 Go 中，文档可见性由标识符的导出规则（exported identifier rule）天然控制：只有首字母大写的函数、类型、变量、常量和方法才会被 godoc 和 go doc 默认收录。这意味着你无需为隐藏 helper 函数而重构代码结构（例如拆分到独立包或文件），只需确保它们使用小写首字母命名即可。
✅ 正确示例（将出现在 godoc 中）：
// GetUserByID retrieves a user by its ID.
func GetUserByID(id int) (*User, error) {
// ...
}
// User represents a registered API user.
type User struct {
ID int `json:"id"`
Name string `json:"name"`
}
❌ 隐藏示例（默认不显示在 godoc 中）：
// parseConfig reads and validates config file — won't appear in docs
func parseConfig(path string) (map[string]string, error) {
// ...
}
// defaultTimeout is internal — ignored by godoc
var defaultTimeout = 30 * time.Second
⚠️ 注意事项：
- 文档注释必须紧邻导出标识符上方（无空行），且格式为 // 单行注释或 /* */ 块注释；多行注释推荐使用 // 连续行以保证最佳解析效果。
- 若需临时查看未导出符号（如调试时），可使用 go doc -u 或启动 godoc 服务时添加 URL 参数 ?m=all（例如 http://localhost:8000/pkg/yourmodule/?m=all），但这仅用于开发验证，不建议在生产文档中启用。
- godoc 已被 Go 官方标记为deprecated（自 Go 1.13 起），推荐迁移到 pkg.go.dev（需发布到公开 Git 仓库并打 tag）；其行为完全遵循相同导出规则，且更稳定、支持模块化索引。
总结：Go 的文档机制是“白名单式”的——你不需要显式排除 helper 函数，只需遵循 Go 的导出约定（小写首字母 = 私有 = 不入文档），即可干净、安全、零配置地实现 API 文档的聚焦呈现。
