GODOC(1)

💖 godoc — the manual, but make it make sense 💖

okay bestie, gather round, because we're talking about godoc, the Go documentation queen, from the General Commands Manual section. she extracts AND generates documentation for Go programs. both. she's multifaceted like that. 👑

---

✨ SYNOPSIS ✨

godoc [flag]

---

🌸 DESCRIPTION 🌸

Godoc extracts and generates documentation for Go programs. that's the whole job description, and she does it flawlessly.

she runs as a web server and presents the documentation as a web page. like, she just serves it up for you. no cap.

godoc -http=:6060

---

🎀 OPTIONS 🎀

• -v — verbose mode. she tells you everything she's doing. oversharing as a service 💅
• -timestamps=true — show timestamps with directory listings
• -index — enable the identifier and full text search index. > heads up bestie: if -index is not set, no search box is shown at all. no index, no search box, no exceptions. 🙈
• -index_files="" — glob pattern specifying index files; if it's not empty, the index is read from these files in sorted order
• -index_throttle=0.75 — the index throttle value. okay so: a value of 0 means no time is allocated to the indexer (which means the indexer will never finish — literally never, she's stuck), and a value of 1.0 means index creation is running at full throttle (other goroutines may get no time while the index is built — she's taking ALL the attention, main character energy fr)
• -index_interval=0 — interval of indexing; a value of 0 sets it to 5 minutes, and a negative value indexes only once at startup
• -play=false — enable playground
• -links=true — link identifiers to their declarations
• -write_index=false — write the index to a file; the file name must be specified with -index_files
• -maxresults=10000 — maximum number of full text search results shown. > no full text index is built if maxresults <= 0
• -notes="BUG" — regular expression matching note markers to show (e.g., "BUG|TODO", ".*")
• -goroot=$GOROOT — Go root directory
• -http=addr — HTTP service address (e.g., '127.0.0.1:6060' or just ':6060')
• -analysis=type,pointer — comma-separated list of analyses to perform:
  • "type": display identifier resolution, type info, method sets, 'implements', and static callees
  • "pointer": display channel peers, callers and dynamic callees (significantly slower — she's gorgeous but she is NOT fast like that)

See https://golang.org/lib/godoc/analysis/help.html for details.

• -templates="" — directory containing alternate template files; if set, the directory may provide alternative template files for the files in $GOROOT/lib/godoc
• -url=path — print to standard output the data that would be served by an HTTP request for path
• -zip="" — zip file providing the file system to serve; disabled if empty

---

🦋 DISCUSSION 🦋

By default, godoc looks at the packages it finds via $GOROOT and $GOPATH (if set). she just goes and finds them herself. independent queen. ✨

When the -index flag is set, a search index is maintained. the index is created at startup.

The index contains both identifier</> and full text</> search information (searchable via regular expressions, yes really 🔥). The maximum number of full text search results shown can be set with the -maxresults flag; if set to 0, no full text results are shown, and only an identifier index but no full text search index is created.

By default, godoc uses the system's GOOS/GOARCH. You can provide the URL parameters "GOOS" and "GOARCH" to set the output on the web page for the target system.

---

💜 presentation mode 💜

The presentation mode of web pages served by godoc can be controlled with the "m" URL parameter; it accepts a comma-separated list of flag names as its value:

• all — show documentation for all declarations, not just the exported ones
• methods — show all embedded methods, not just those of unexported anonymous fields
• src — show the original source code rather then the extracted documentation
• text — present the page in textual (command-line) form rather than HTML
• flat — present flat (not indented) directory listings using full paths

For instance, http://golang.org/pkg/math/big/?m=all,text shows the documentation for all (not just the exported) declarations of package big, in textual form (as it would appear when using godoc from the command line: godoc -src math/big .*).

---

🌈 the .zip era 🌈

By default, godoc serves files from the file system of the underlying OS. Instead, a .zip file may be provided via the -zip flag, which contains the file system to serve. The file paths stored in the .zip file must use slash ('/') as path separator; and they must be unrooted. $GOROOT (or -goroot) must be set to the .zip file directory path containing the Go root directory. for instance, for a .zip file created by the command:

zip go.zip $HOME/go

one may run godoc as follows:

godoc -http=:6060 -zip=go.zip -goroot=$HOME/go

---

🧚 how the docs actually get made 🧚

Godoc documentation is converted to HTML or to text using the go/doc package; see https://golang.org/pkg/go/doc/#ToHTML for the exact rules. Godoc also shows example code that is runnable by the testing package; see https://golang.org/pkg/testing/#hdr-Examples for the conventions. See "Godoc: documenting Go code" for how to write good comments for godoc: http://golang.org/doc/articles/godoc_documenting_go_code.html

---

👑 AUTHOR 👑

This manual page was written by Michael Stapelberg <stapelberg@debian.org>, for the Debian project (and may be used by others). shoutout to Michael, fr fr 🫶

---

okay so that's the whole thing bestie, every flag, every default, every warning, nothing skipped, we ate that 💅

and that's a wrap on the godoc manual page, GODOC(1), dated 2019-07-31. slay, go read some docs, ily 🎀✨