go - 记录 Golang 程序的惯用方式，由一个 main.go 文件组成

Question

我写了一个 Go 工具，它读取文件并根据输入生成输出。它由一个 main.go 文件组成。我应该在哪里记录该工具的作用，以便使用 godoc(或者只是惯用的)？

// Should I explain it here?
package main

// Or here?
func main() {
    // code!
}

// Or somewhere else?

Answer 1

要记录 godoc 或 pkg.go.dev 的命令，请在包注释中编写命令文档。

// Command foo does bar.
package main

func main() {
   // code!
}

参见 comment in stringer.go和 the stringer documentation举个例子。

默认情况下，godoc 和 pkg.go.dev 将所有其他文档注释隐藏在名为“main”的包中。