8

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?
Jonathan Hall
  • 75,165
  • 16
  • 143
  • 189
Kiril
  • 6,009
  • 13
  • 57
  • 77
  • 5
    You may want to look at the following article about it https://blog.golang.org/godoc-documenting-go-code . It perfectly explains idiomatic way of preparing Godoc – cengineer Apr 26 '17 at 15:19
  • Yeah, I read it, but it's about packages and exported functions only. Here I have the main package and no exported functions. – Kiril Apr 26 '17 at 15:19
  • 2
    Then most probably you have also read that article https://godoc.org/golang.org/x/tools/cmd/godoc . Basically when you want to look at the doc of this package/function, you are going to run "godoc main" like you do on any other package, right? So since it is also a package, all idiomatic ways are also valid for that too. – cengineer Apr 26 '17 at 15:29
  • 1
    godoc is intended to document Go library APIs; since you can't import main, there's nothing in a main package worth documenting from that standpoint. If you want to document what the tool does, README.md or the like is probably the better and more idiomatic solution. – Adrian Apr 26 '17 at 18:32

1 Answers1

13

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

Charlie Tumahai
  • 113,709
  • 12
  • 249
  • 242
  • 1
    As an example you can look at https://github.com/golang/tools/blob/master/cmd/stringer/stringer.go and try to run 'godoc cmd/stringer' – n-canter Jul 28 '17 at 19:23