在Go中为单文件main.go程序添加文档时，应将工具功能说明写在包注释（package comment）位置，即package main上方的首段注释，这是godoc和pkg.go.dev识别命令用途的唯一标准位置。
在go中为单文件main.go程序添加文档时，应将工具功能说明写在包注释（package comment）位置，即`package main`上方的首段注释，这是godoc和pkg.go.dev识别命令用途的唯一标准位置。
为Go命令行工具（command）编写符合惯用法（idiomatic）的文档，关键在于文档位置的准确性，而非内容详略。当你仅有一个 main.go 文件时，godoc 和 pkg.go.dev 会将整个文件视为一个名为 main 的包；而根据 Go 工具链约定：只有紧邻 package main 声明之前的顶层包注释（package comment），才会被提取并展示为该命令的概览文档。其他位置的注释——例如函数内、main() 函数上方、或包声明之后的注释——均会被忽略。
✅ 正确写法（推荐）：
// Command fileproc reads input files and generates structured output based on configurable rules.
// It supports JSON, YAML, and plain text inputs, and outputs formatted reports to stdout.
package main
import (
"fmt"
"os"
)
func main() {
if len(os.Args) < 2 {
fmt.Fprintln(os.Stderr, "Usage: fileproc <file1> [file2] ...")
os.Exit(1)
}
// 实际逻辑...
}⚠️ 注意事项：
- 包注释必须是连续的、以
//开头的多行注释块，且严格位于package main之前，且中间不能有空行或其他声明； - 注释首句应以
Command xxx开头（如Command fileproc），这是 pkg.go.dev 解析命令名称的标准模式； - 避免在
main()函数上方单独加注释（如// Entrypoint...），这类注释不会出现在生成的文档中； - 若需补充详细用法（如 flag 说明、环境变量、退出码），建议在
main()中通过flag.Usage或自定义帮助文本实现，而非依赖 godoc —— 因为godoc对main包的函数/变量注释默认隐藏。
? 验证方法：
本地运行 godoc -http=:6060，访问 http://localhost:6060/pkg/your-module-name/（确保已 go mod init），或直接提交至 GitHub 后观察 pkg.go.dev 是否正确渲染命令描述 —— 这是最权威的实践检验方式。
遵循这一约定，你的单文件 Go 工具就能无缝融入 Go 生态的文档体系，既专业又可发现（discoverable）。
立即学习“go语言免费学习笔记（深入）”；
