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 notes I've written to myself using //BUG and subdirectories.

Godoc only displays exported functions and seems to have no way to display unexported / functions from main. I would find it useful to see a list of functions in main. Since this isn't supported, I tend to shove a list of functions at the top of the package description but this feels like a workaround.

Since I have to manually update the list of functions, I often put as much code in packages as I can so it's exported and thus documented. Is this a good idea? What should I do about the list of functions in main?

Example:

COMMAND DOCUMENTATION

Package main implements a web server, template renderer and DAL for MySQL.

<filename.go>

    <function>(<signature>)

main.go

    main()
    bootstrap() error
    <more functions here>


BUGS

    [filename.go] <whatever...>


SUBDIRECTORIES

    auth
    common
    debug
    storage
    <more packages here>

Answer 1

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.

Answer 2

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.