What steps are needed to document `package main` in Godoc?

Question

Godoc is a great tool for documenting packages, however it seems to be less useful when it\'s used against package main. I\'ll see an output that only displays the

Answer 1

AFAIK, you already have the answer to your question. I can think of two alternative solutions:

1. Maintain a fork of godoc that shows functions for main packages. (And you'd then have to run an instance of it yourself on a web server. The downside is that people going straight to godoc.org for your package documentation will miss out.)
2. Separate your main packages into sub-packages such that the main package is small or minimal. Documentation could then be read in those sub-packages. But as far as I know, this is not in widespread practice.

I think in general, godoc is for package documentation. Documentation for main packages is really only useful to people editing the source code of that package---so the documentation conceivably doesn't need to be publicized. On the other hand, this lacks the nice presentation/organization of godoc.

As a compromise, if you really want to publicize the documentation, I'd recommend an overview of the architecture of your program rather than a play-by-play of each function.

Answer 2

You need to build a slightly modified version of godoc to document main packages.

Please see https://github.com/golang/go/issues/5727.

tl;dr:

1. Modify the following line in $GOPATH/src/golang.org/x/tools/godoc/server.go

   - info.IsMain = pkgname == "main"
   + info.IsMain = false && pkgname == "main"
   

2. Build and install with go install golang.org/x/tools/cmd/godoc.

$GOPATH/bin/godoc should now behave as you wish.