I came across a discussion on slack where someone was pretty confused about various corners of godoc. I wrote a blog post (well, 4 actually, but I’ve only published one of them so far) about some of the things that came up in the discussion.
I didn’t think to post a link to it here, but when I shared it with the original poster, they said they thought other people would enjoy it, so here it is:
Nice!
Are you covering go doc (vs godoc) in the future posts?
Yes! I hadn’t thought of that, but that’s a great idea.
Good job! Another topic I see pop up on Stackoverflow every month is finding out which Types satisfy an Interface and vice versa. I always end up pointing people to https://golang.org/lib/godoc/analysis/help.html, but it definitely needs some more attention.
I posted the godoc vs go doc, article today, @mem.
If I got any of the details wrong, please let me know.
http://whipperstacker.com/2015/09/30/go-documentation-godoc-godoc-godoc-org-and-go-doc/
Nice!
The only thing I’m missing is the difference between golang.org/x/tools/godoc (the godoc command) and cmd/go/doc (the doc tool in the go command).
There are a few things that are different between the two, but for me the most important one is what each of them do when called without arguments.
godoc will spit out its usage
go doc will print out the documentation for the package in the current directory
Thanks again!
Oooh, yes. So many go docs! I’ll take a stab at updating the article. Thanks!
I updated the post–thanks again.
The reason for “go doc” is that it is designed for command-line use. Godoc is a web server first and a command-line tool as little more than an afterthought.
From the command line go doc is more convenient, has better defaults, and has some rudimentary search capability. Also, and perhaps most important, it has Go-like syntax: You write “go doc gob.Decoder” not “godoc encoding/gob Decoder”.
With godoc.org, godoc, go doc, and go/doc, I bet it can be very confusing for beginners so it’s important to single out the distinctive features and reasons for each.
-rob
Thanks so much for clarifying the reasoning, that helps a lot. I’ll incorporate this into the article.
Update: I’ve updated the post.
This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.