Search code examples
godocumentationidiomsgodoc

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

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?
Solution

  • 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".