/rant
Whereas I don’t actually need further proof, the state of Go in 2022 additional convinces me that it’s however one more self-importance mission thrown (and I take advantage of that time period advisedly) out into the world + canine by sensible however boastful builders at Google (and wherever else folks on the core staff come from).
To wit, and I quote (from weblog submit dated 31 March 2011, posted as code as a consequence of hyperlink limits):
The Go mission takes documentation significantly.
(From weblog submit dated 31 March 2011: https://go.dev/weblog/godoc)
On the high of the weblog there's a hyperlink to a June 2022 replace at https://go.dev/doc/remark
Proper.
But NEITHER of these pages comprise (on the fast web page) clear, succinct directions for putting in the mandatory instruments to really create documentation for customized Go modules. Additional, if documentation is so necessary, you may rightfully ask:
Why ought to I’ve to INSTALL a instrument to create documentation, separate from putting in the language
(particularly because the language is distributed with different instruments).
You bought me – ask the Go staff.
Go is now at 1.18.3. But, after losing time making an attempt to find out why godoc didn;t work, I discover within the readme for go 1.13 (date unspecified on web page; posted as code as a consequence of hyperlink limits):
godoc and go doc
The godoc webserver is not included in the primary binary distribution. To run the godoc webserver domestically, manually set up it first:
go get golang.org/x/instruments/cmd/godoc
godoc
So, it’s necessary, however we within the Go group can’t be bothered to incorporate it in precise distributions – go (the verb) determine it out for your self.
So as to add additional insult to harm, with v1.18.3, you may’t in reality use get except you soar via different hoops which are required for 1.18.3 use of get. (determining what the arcane guidelines are is left as an train for the reader)
However OK. Set up godoc:
C:UsersJack>go set up golang.org/x/instruments/cmd/godoc@newest
go: downloading golang.org/x/instruments v0.1.11
go: downloading golang.org/x/sys v0.0.0-20211019181941-9d821ace8654
go: downloading golang.org/x/web 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
Seems to have put in OK.
However does it work? Fats probability.
As a local English speaker, I feel I do know what this sentence (from Godoc: documenting Go code – The Go Programming Language) says, and what ought to occur after I run the command in daring on this paragraph:
Your personal code can current good documentation simply by having feedback as described above. Any Go packages put in inside $GOROOT/src/pkg and any GOPATH work areas will already be accessible by way of godoc’s command-line and HTTP interfaces, and you’ll specify further paths for indexing by way of the -path flag or simply by working “godoc .” within the supply listing.
Foolish me! Right here’s the output (sourcedir accommodates a .go file with some documentation, its .mod file, and two sub-folders which additionally comprise .go and .mod information):
C:GProjectsexamplesourcedir>godoc .
Sudden arguments. Use "go doc" for command-line assist output as an alternative. For instance, "go doc fmt.Printf".
utilization: godoc -http=localhost:6060
-goroot string
Go root listing (default "C:Program RecordsdataGo")
-http string
HTTP service deal with (default "localhost:6060")
-index
allow search index
-index_files string
glob sample specifying index information; if not empty, the index is learn from these information in sorted order
-index_interval period
interval of indexing; 0 for default (5m), detrimental to solely index as soon as at startup
-index_throttle float
index throttle worth; 0.0 = no time allotted, 1.0 = full throttle (default 0.75)
-links
hyperlink identifiers to their declarations (default true)
-maxresults int
most variety of full textual content search outcomes proven (default 10000)
-notes string
common expression matching notice markers to point out (default "BUG")
-play
allow playground
-templates string
load templates/JS/CSS from disk on this listing
-timestamps
present timestamps with listing listings
-url string
print HTML for named URL
-v verbose mode
-write_index
write index to a file; the file title have to be specified with -index_files
-zip string
zip file offering the file system to serve; disabled if empty
UNBELIEVABLE! (besides that, from painful expertise making an attempt to make use of different self-importance tasks, very plausible).
Although I didn’t attempt setting values for all flags, I did attempt particularly utilizing-http=localhost:6060 (identical outcomes as above)
-http=localhost:6060 -goroot . (on a transparent disk you may search perpetually – i.e., the server seems to begin however hangs):
C:GProjectsexamplesourcedir>godoc -v -http=localhost:6060 -goroot .
utilizing module mode; GOMOD=C:GProjectsexamplesourcedirgo.mod
2022/06/29 12:23:00 newDirTree studying /favicon.ico: file doesn't exist
2022/06/29 12:23:00 Go Documentation Server
2022/06/29 12:23:00 model = go1.18.3
2022/06/29 12:23:00 deal with = localhost:6060
2022/06/29 12:23:00 goroot = .
2022/06/29 12:23:00 search index disabled
title area {
/:
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:UsersJackgopkgmodgolang.orgxsys@v0.0.0-20220624220833-87e55d714810), 20) /
/src/examplesourcedir:
gated(os(.), 20) /src/examplesourcedir
gated(os(C:GProjectsexamplesourcedir), 20) /
}
2022/06/29 12:23:00 beginning HTTP server (and ready for Godot...)
Come on, Go group. Get your act collectively.
For the file, I’m prepared to RTFM, nevertheless poorly written/inconsistent it could be, and I acknowledge that my typically dyslexic eye-brain connection generally misreads. However it’s past the pale that performance touted as elementary and necessary doesn’t work out-of-the-box.
It’s at finest indicative of sloppy releases, and at worst suggestive of incompetence.
/rant
That stated, for individuals who made it via the rant, I might admire any steerage from anybody who has resolved this explicit challenge.
Jack
