Idiomatic way of documenting a Golang program, consisting of one main.go file

Question

I wrote a Go tool which reads files and produces output based on the input. It consists of one main.go file. Where do I document what the tool does, in order to make use of godoc (or just be idiomatic)?

// Should I explain it here?
package main

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

// Or somewhere else?

Answer 1

To document a command for godoc or pkg.go.dev, write the command documentation in the package comment.

// Command foo does bar.
package main

func main() {
   // code!
}

See the comment in stringer.go and the stringer documentation for an example.

By default, godoc and pkg.go.dev hide all other doc comments in a package with the name "main".