/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