The utility (or lack thereof) of godoc

/rant
While I don’t really need additional evidence, the state of Go in 2022 further convinces me that it is but yet another vanity project thrown (and I use that term advisedly) out into the world + dog by smart but arrogant developers at Google (and wherever else people on the core team come from).

To wit, and I quote (from blog post dated 31 March 2011, posted as code due to link limits):

The Go project takes documentation seriously.

(From blog post dated 31 March 2011: https://go.dev/blog/godoc)
At the top of the blog there is a link to a June 2022 update at https://go.dev/doc/comment

Right.

Yet NEITHER of those pages contain (on the immediate page) clear, succinct instructions for installing the necessary tools to actually create documentation for custom Go modules. Further, if documentation is so important, you might rightfully ask:

Why should I have to INSTALL a tool to create documentation, separate from installing the language

(especially since the language is distributed with other tools).

You got me - ask the Go team.

Go is now at 1.18.3. Yet, after wasting time trying to determine why godoc didn;t work, I find in the readme for go 1.13 (date unspecified on page; posted as code due to link limits):

godoc and go doc
The godoc webserver is no longer included in the main binary distribution. To run the godoc webserver locally, manually install it first:
 
go get golang.org/x/tools/cmd/godoc
godoc

So, it’s important, but we in the Go group can’t be bothered to include it in actual distributions - go (the verb) figure it out for yourself.

To add further insult to injury, with v1.18.3, you can’t in fact use get unless you jump through other hoops that are required for 1.18.3 use of get. (figuring out what the arcane rules are is left as an exercise for the reader)

But OK. Install godoc:

C:\Users\Jack>go install golang.org/x/tools/cmd/godoc@latest
go: downloading golang.org/x/tools v0.1.11
go: downloading golang.org/x/sys v0.0.0-20211019181941-9d821ace8654
go: downloading golang.org/x/net v0.0.0-20211015210444-4f30a5c0130f
go: downloading github.com/yuin/goldmark v1.4.1
go: downloading golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4

Appears to have installed OK.

But does it work? Fat chance.

As a native English speaker, I think I know what this sentence (from Godoc: documenting Go code - The Go Programming Language) says, and what should happen when I run the command in bold in this paragraph:

Your own code can present good documentation just by having comments as described above. Any Go packages installed inside $GOROOT/src/pkg and any GOPATH work spaces will already be accessible via godoc’s command-line and HTTP interfaces, and you can specify additional paths for indexing via the -path flag or just by running “godoc .” in the source directory.

Silly me! Here’s the output (sourcedir contains a .go file with some documentation, its .mod file, and two sub-folders which also contain .go and .mod files):

C:\GProjects\example\sourcedir>godoc .
Unexpected arguments. Use "go doc" for command-line help output instead. For example, "go doc fmt.Printf".
usage: godoc -http=localhost:6060
  -goroot string
        Go root directory (default "C:\\Program Files\\Go")
  -http string
        HTTP service address (default "localhost:6060")
  -index
        enable search index
  -index_files string
        glob pattern specifying index files; if not empty, the index is read from these files in sorted order
  -index_interval duration
        interval of indexing; 0 for default (5m), negative to only index once at startup
  -index_throttle float
        index throttle value; 0.0 = no time allocated, 1.0 = full throttle (default 0.75)
  -links
        link identifiers to their declarations (default true)
  -maxresults int
        maximum number of full text search results shown (default 10000)
  -notes string
        regular expression matching note markers to show (default "BUG")
  -play
        enable playground
  -templates string
        load templates/JS/CSS from disk in this directory
  -timestamps
        show timestamps with directory listings
  -url string
        print HTML for named URL
  -v    verbose mode
  -write_index
        write index to a file; the file name must be specified with -index_files
  -zip string
        zip file providing the file system to serve; disabled if empty

UNBELIEVABLE! (except that, from painful experience attempting to use other vanity projects, very believable).

Though I did not try setting values for all flags, I did try specifically using
-http=localhost:6060 (same results as above)

-http=localhost:6060 -goroot . (on a clear disk you can seek forever - i.e., the server appears to start but hangs):

C:\GProjects\example\sourcedir>godoc -v -http=localhost:6060 -goroot .
using module mode; GOMOD=C:\GProjects\example\sourcedir\go.mod
2022/06/29 12:23:00 newDirTree reading /favicon.ico: file does not exist
2022/06/29 12:23:00 Go Documentation Server
2022/06/29 12:23:00 version = go1.18.3
2022/06/29 12:23:00 address = localhost:6060
2022/06/29 12:23:00 goroot = .
2022/06/29 12:23:00 search index disabled
name space {
    /:
            gated(os(.), 20) /
    /favicon.ico:
            mapfs /favicon.ico
    /lib/godoc:
            mapfs /
    /src/golang.org/x/sys:
            gated(os(.), 20) /src/golang.org/x/sys
            gated(os(C:\Users\Jack\go\pkg\mod\golang.org\x\sys@v0.0.0-20220624220833-87e55d714810), 20) /
    /src/example\sourcedir:
            gated(os(.), 20) /src/example\sourcedir
            gated(os(C:\GProjects\example\sourcedir), 20) /
}
2022/06/29 12:23:00 starting HTTP server (and waiting for Godot...)

Come on, Go group. Get your act together.

For the record, I am willing to RTFM, however poorly written/inconsistent it might be, and I acknowledge that my often dyslexic eye-brain connection sometimes misreads. But it is beyond the pale that functionality touted as fundamental and important does not work out-of-the-box.

It is at best indicative of sloppy releases, and at worst suggestive of incompetence.
/rant

That said, for those who made it through the rant, I would appreciate any guidance from anyone who has resolved this particular issue.

Jack

1 Like

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.