Go 语言自带的 Godoc 工具能够从源代码注释中提取文档，生成可浏览的 API 页面。然而，很多专注于命令行工具或可执行程序的开发者会发现，自己的 package main 在 Godoc 中要么无法显示，要么只展示一个空壳。这并非工具缺陷，而是因为 main 包的特殊地位以及文档注释的约定没有满足。要让 Godoc 完整文档化 main 包，需要理解其解析规则并针对性地组织代码和注释。
为什么 package main 的文档常常一片空白
Godoc 在生成文档时会扫描每一个包的源文件，提取包注释和所有导出标识符的注释。包注释必须直接出现在 package 声明之前，中间不能有空行，否则会被忽略。对于 main 包，很多开发者习惯把包声明写在 main.go 的顶部，却没有添加任何包注释，或者注释与 package 声明之间空了一行，导致 Godoc 只显示包路径而没有概要说明。
另一个关键因素是导出标识符。Godoc 的详细页面主要罗列导出的类型、函数、常量和变量。可导入的库包通常有大量导出内容，而 main 包作为程序入口，大多数情况下只有 main 函数和若干未导出的辅助函数，没有符合 Godoc 收录条件的导出符号。因此即使包注释存在，详细页面也往往只有一句包描述，看起来就像是文档不完整。
此外，许多开发者误以为 main 包不需要生成文档，因为外部代码无法导入它。这种观点忽略了 CLI 工具同样需要向使用者说明参数格式、配置项和退出码等信息。只要按照 Godoc 的规则组织 main 包，同样能够生成清晰、有用的参考页面。
建立 doc.go 并编写规范的包注释
解决 main 包文档缺失的第一步是创建 doc.go 文件。Godoc 不强制要求包注释必须放在特定文件名中，但社区惯例是单独使用 doc.go 来承载包级注释。这样做的好处是：注释与实现代码分离，阅读更清晰；同时避免因为业务代码改动导致注释与 package 声明之间意外出现空行。
包注释以 // 或 /* */ 书写，必须紧邻 package main 语句。下面是一个规范的示例：
// Package main 提供了一个用于批量处理日志文件的命令行工具。 // // 该工具支持从标准输入读取日志，按指定规则过滤后输出统计结果。 // 运行方式： // logtool -input access.log -level error // // 更多配置请参考 README.md。 package main
上面的注释使用了空行分段，并且用缩进表示代码示例，Godoc 会将其渲染为独立的代码块。包注释中可以包含标题、列表、段落和链接，但要注意不要使用 Markdown 语法，Godoc 有自己的简单格式化规则。注释的第一句话会被提取为包概要，显示在包列表页中，因此要简洁明了地说明包的用途。
如果项目已经存在，检查所有源文件，确保只有 doc.go 中的注释紧邻 package main，其他文件中的 package 声明前不要有多余注释。多个文件中的包注释会被 Godoc 合并，但最好统一放在 doc.go 中管理。
为 main 包添加导出符号和示例函数
虽然 main 包不被外部导入，但 Godoc 并不限制在 main 包中定义导出的类型、常量、变量和函数。这些导出符号会被完整收录到文档详细页面，帮助使用者了解命令行工具的核心概念。例如，可以定义一个 Config 类型来集中展示所有配置项：
// Config 保存命令行工具运行所需的全部配置项。
type Config struct {
// Input 指定输入文件路径，为空时读取标准输入。
Input string
// Level 指定日志过滤级别，支持 debug、info、error。
Level string
}
// ParseArgs 解析命令行参数并返回配置对象。
// 如果参数格式错误，返回对应的 error。
func ParseArgs(args []string) (*Config, error) {
// 实现略
return nil, nil
}
这些导出符号不会影响 main 函数的执行，也不会被其他包导入，但 Godoc 会把它们作为包 API 的一部分展示。需要注意的是，结构体字段、常量、函数参数和返回值都应该添加注释，Godoc 会将这些注释与对应符号关联起来。
示例函数是另一种高质量文档形式。遵循 Example 前缀的命名规则，Godoc 会自动将其放入文档页面并附带可运行的代码块。对于 main 包，示例函数通常用来演示参数解析、配置加载或核心处理流程：
// ExampleParseArgs 演示如何解析命令行参数。
func ExampleParseArgs() {
cfg, err := ParseArgs([]string{"-input", "app.log", "-level", "error"})
if err != nil {
fmt.Println(err)
return
}
fmt.Println(cfg.Level)
// Output: error
}
示例函数必须以 Example 开头，后接导出的标识符名称，或者直接使用 Example 表示包级示例。函数体末尾的 // Output: 注释声明了标准输出内容，Godoc 会将其作为预期结果展示。测试框架也会执行这些示例函数并校验输出，保证文档与实现保持一致。
本地启动 Godoc 并验证 main 包文档
完成上述步骤后，可以使用 go doc 命令快速查看包文档。在项目根目录下执行 go doc . 会输出当前包的概要、导出符号和示例函数；go doc -all . 会显示包括未导出符号在内的完整内容。如果一切正常，你应该能看到包描述、Config 结构体、ParseArgs 函数以及 ExampleParseArgs 示例。
如果需要浏览 HTML 页面，可以启动本地 Godoc 服务。在终端运行 godoc -http=:6060，然后访问 http://localhost:6060/pkg/你的模块路径/。对于使用 Go Modules 的项目，Godoc 可能会显示模块路径，例如 ippipp.com/logtool，只要包注释和导出符号正确，页面就会完整呈现。如果找不到包，检查 GO111MODULE 设置或尝试在项目目录下运行 go doc，因为 go doc 对模块模式支持更好。
常见的问题包括：包注释没有显示，通常是因为注释与 package 关键字之间出现了空行；示例函数没有出现，可能是函数名拼写错误或没有 // Output: 注释；文档页面过旧，可以尝试刷新浏览器缓存或重启 Godoc 服务。通过反复使用 go doc 验证，可以快速定位问题所在。
GodocGo文档package main修改时间：2026-08-26 05:23:41