GoDoc 会按类型对常量、方法和函数进行分组，因此使用自定义类型声明的常量（如 const Info Level = iota）将被归入该类型的文档区块，而非包级“Constants”章节——这是 GoDoc 的固有行为，无法通过注释或配置强制提升至包级别。
godoc 会按类型对常量、方法和函数进行分组，因此使用自定义类型声明的常量（如 `const info level = iota`）将被归入该类型的文档区块，而非包级“constants”章节——这是 godoc 的固有行为，无法通过注释或配置强制提升至包级别。
在 Go 文档生成体系中，godoc（以及现代 go doc 和 pkg.go.dev）遵循严格的声明归属原则：一个标识符的文档位置由其直接所属的声明作用域决定。当常量被显式赋予自定义类型时，例如：
type Level int
const (
Info Level = iota
Warning Level = iota
Error Level = iota
)尽管这些常量在语法上位于包作用域，但 godoc 将其语义视为 Level 类型的具名值集合，因而统一归档到 type Level 的文档区块下，并在该类型定义附近渲染为 “Constants” 子节（而非包顶层的 Constants 章节）。
相比之下，无类型常量：
const (
Info = iota
Warning
Error
)因未绑定任何用户定义类型，被 godoc 视为纯包级常量，故自然出现在包文档顶部的 “Constants” 章节中。
✅ 关键结论与实践建议：
- 不可绕过：不存在 //go:doc 指令、注释标记或构建参数能改变此行为。这是 godoc 解析器的底层设计逻辑，非 bug，亦无计划修改。
- 设计权衡：该机制强化了类型安全的可发现性——调用方查阅 Level 类型文档时，能立即看到其合法取值，提升 API 可用性。
-
替代方案（若需包级可见性）：
- 保留无类型常量用于通用场景，另通过类型别名或转换函数桥接（例如 func (Level) String() string 配合 fmt.Stringer）；
- 在包级文档注释（// Package xxx ...）中手动列出关键常量并链接至对应类型，例如：
// Package log provides structured logging. // // Predefined log levels: // - Info (see type Level) // - Warning (see type Level) // - Error (see type Level) package log
总之，这不是文档生成的缺陷，而是 Go 强类型哲学在工具链中的自然体现：类型即契约，契约即文档上下文。 理解并顺应这一规则，才能写出既类型安全又易于理解的 Go API。
