在 go 中为仅含 main.go 的命令行工具编写文档时，应将工具功能说明写在 package main 的包注释中，这是 godoc 和 pkg.go.dev 唯一识别并展示的公共文档位置。
在 go 中为仅含 main.go 的命令行工具编写文档时，应将工具功能说明写在 package main 的包注释中，这是 godoc 和 pkg.go.dev 唯一识别并展示的公共文档位置。
Go 的文档工具（如 godoc 和 pkg.go.dev）对 main 包有特殊处理：默认仅显示 package 声明上方的包注释（package comment），而忽略 main() 函数内或其它位置的任何文档注释。这意味着，即使你在 main 函数前添加了详细注释，或为标志解析、核心逻辑写了 doc comment，它们都不会出现在生成的文档页面中。
✅ 正确做法：将工具用途、输入输出行为、典型用法等关键信息，以完整、简洁、面向用户的语言，写在 package main 语句正上方的块注释中：
// Command fileproc reads text files, extracts lines matching a pattern,
// and outputs statistics in JSON format.
// It supports glob patterns, case-insensitive search, and optional line numbering.
//
// Usage:
// fileproc -pattern "error" *.log
// fileproc -i -n access.log
package main
import (
"flag"
"fmt"
"os"
)
func main() {
pattern := flag.String("pattern", "", "regex pattern to match")
ignoreCase := flag.Bool("i", false, "case-insensitive matching")
numberLines := flag.Bool("n", false, "prefix matched lines with line numbers")
flag.Parse()
// ... implementation
}⚠️ 注意事项：
- 包注释必须紧邻
package main，中间不能有空行（否则会被视为普通注释，不被识别为 package comment）； - 避免在
main()函数上方单独写函数级注释（如// main runs the CLI...），它不会出现在文档中，且易造成冗余； - 若项目后续演变为多文件命令（如拆分出
cmd/或internal/子包），仍应保持顶层main.go的包注释作为命令摘要，其余实现细节可放在对应子包文档中； - 推荐遵循 Go Doc Comments 规范：首句独立成段、使用祈使语气（如 “Command foo does…”）、避免 markdown、不加
@标签。
总结：对于单文件 Go 命令工具，package main 上方的注释即其官方文档入口——它是用户通过 go doc、IDE 悬停提示或 pkg.go.dev 首页看到的第一手信息。写好它，就是写好你的工具门面。
