godoc 会按类型对常量自动分组，使用自定义类型声明的常量（如 const info level = iota）将归属到该类型的文档节中，而非包级“constants”章节——这是 go 文档生成的固有行为，无法通过语法或标记强制提升至包级别。
godoc 会按类型对常量自动分组，使用自定义类型声明的常量（如 const info level = iota）将归属到该类型的文档节中，而非包级“constants”章节——这是 go 文档生成的固有行为，无法通过语法或标记强制提升至包级别。
在 Go 的文档生成体系中，godoc（以及现代 go doc 和 pkg.go.dev）遵循严格的声明归属原则：一个标识符的文档位置由其直接所属的声明作用域决定。当常量被显式赋予自定义类型时，例如：
type Level int
const (
Info Level = iota
Warning Level
Error Level
)Info、Warning、Error 在语义上已不再是“无类型常量”，而是 Level 类型的具名值。因此，godoc 将它们视为 Level 类型的组成部分，并统一归入 type Level 的文档区块下——通常显示在类型定义之后、方法列表之前，位于页面中段，而非顶部独立的 Constants 节。
这与以下未带类型的写法形成鲜明对比：
const (
Info = iota // 无类型整数常量
Warning
Error
)此时 Info 等属于包作用域的未类型化常量，godoc 会将其聚合到包级 Constants 标题下（若存在至少一个未类型化常量），位置醒目、易于发现。
⚠️ 重要说明：不存在绕过该机制的官方方式
- //go:generate、//nolint 或其他编译指令对 godoc 分组逻辑无效；
- // Package xxx 注释仅影响包摘要，不改变符号归属；
- 尝试用别名类型（type Level = int）或接口嵌入也无法改变常量绑定关系；
- go doc -all 或 pkg.go.dev 均遵循同一规则，属设计一致性，非 bug。
✅ 实践建议
- 优先语义清晰性：若 Info/Warning/Error 本质是 Level 的取值集合，将其置于 type Level 下反而是更准确的文档表达——读者能立即理解其类型契约与用途边界。
- 补充包级文档注释：在包注释中明确说明：“常见日志等级定义于 type Level，包括 Info、Warning 和 Error”，并提供跳转提示（如 See type Level for available constants.）。
- 必要时拆分设计：若强依赖包级常量可见性（如供其他包广泛引用且需快速定位），可保留无类型常量 + 显式类型转换：
const (
Info = iota
Warning
Error
)
type Level int
func (l Level) String() string { /* ... */ }此时 godoc 仍会在顶部显示 Constants，而 Level 作为独立类型提供语义封装——二者职责分离，兼顾可发现性与类型安全。
总之，这不是限制，而是 Go 文档系统对“类型即契约”理念的忠实体现：常量的位置，本质上是其类型归属的自然映射。
