godoc 会按类型组织文档结构，当常量使用自定义类型声明时（如 const info level = iota），它们将被归入该类型的文档区块，而非包级 constants 标题下——这是 godoc 的固有行为，无法通过注释或配置强制提升至包层级。
godoc 会按类型组织文档结构，当常量使用自定义类型声明时（如 const info level = iota），它们将被归入该类型的文档区块，而非包级 constants 标题下——这是 godoc 的固有行为，无法通过注释或配置强制提升至包层级。
在 Go 的文档生成体系中，godoc（以及现代替代工具如 pkg.go.dev）严格遵循“按声明归属分组”原则：常量、变量、函数、方法等的文档位置，由其直接所属的语法作用域决定，而非语义意图。
例如，以下代码中未使用自定义类型：
// package level constants —— will appear under "CONSTANTS" section
const (
Info = iota
Warning
Error
)生成的文档会在页面顶部清晰展示 CONSTANTS 标题，并列出全部常量。
但一旦引入显式类型绑定：
type Level int
// typed constants —— will appear under "type Level" section, NOT at package level
const (
Info Level = iota
Warning
Error
)此时 Info、Warning、Error 在 AST 层面被视为 Level 类型的类型关联常量（typed constants），godoc 将其视为 Level 类型定义的一部分，因此统一收拢至 type Level 的文档区块内（通常位于类型声明下方，方法之前），而包级 Constants 区域保持空白。
✅ 这是设计使然，非 bug 或配置缺失。Go 团队明确表示：
“Constants with explicit types are grouped under their type. There is no mechanism to ‘promote’ them to package scope in generated docs.”
（来源：golang/go issue #19572）
实用建议与权衡方案
| 方案 | 说明 | 适用场景 |
|---|---|---|
| 保持类型化常量 + 完善类型文档 | 在 type Level 的注释中明确说明其取值含义，例如： go // Level specifies log severity. // // Predefined levels: // - Info // - Warning // - Error type Level int | ✅ 推荐。符合 Go 惯例，类型安全，文档可读性高；用户查看 Level 类型时即能获取完整上下文。 |
|
| 使用未类型化常量 + 显式转换 | go const ( Info = iota Warning Error ) // Usage: log.SetLevel(Level(Info)) |
⚠️ 降低类型安全性（需手动转换），但常量可见于包级 CONSTANTS；仅适用于对文档位置敏感且可接受类型松散的内部工具库。 |
| 补充包级文档注释 | 在包注释（package xxx // ...）或 // Package xxx 块中添加说明段落： go // Constants // The following constants represent standard log levels: // Info, Warning, Error |
✅ 零成本增强可发现性，不改变生成结构，适合作为辅助说明。 |
总结
- ❌ 不存在 //go:doc package 或类似指令可强制将类型化常量“提升”至包级 Constants 区域；
- ✅ 正确做法是拥抱 GoDoc 的组织逻辑：为类型撰写详实文档，让常量自然成为其语义的一部分；
- ? 最终用户查阅体验取决于整体文档质量，而非单纯依赖标题位置——清晰的类型说明 + 示例用法，远胜于机械地追求“Constants”出现在顶部。
遵循这一原则，你的 API 文档将更稳健、可维护，也更符合 Go 生态的协作预期。
