Golang中godoc的实用价值探讨

Golang中godoc的实用价值探讨 /吐槽

虽然我并不需要更多证据，但Go在2022年的状况进一步让我确信，它不过是谷歌（以及核心团队其他成员来自的地方）那些聪明但傲慢的开发者们（我特意使用这个词）抛到世界上的又一个面子工程。

具体来说，我引用（来自2011年3月31日的博客文章，由于链接限制以代码形式发布）：

Go项目非常重视文档。

(来自2011年3月31日的博客文章：https://go.dev/blog/godoc)
博客顶部有一个指向2022年6月更新的链接：https://go.dev/doc/comment

好吧。

然而，这两个页面都没有（在直接页面上）提供清晰、简洁的说明，指导如何安装必要的工具来为自定义的**Go**模块实际创建文档。此外，如果文档如此重要，你可能会理所当然地问：

为什么我必须安装一个工具来创建文档，这独立于安装语言本身

（尤其是因为语言发行版中已经包含了其他工具）。

你问住我了——去问Go团队吧。

Go现在已经是1.18.3版本了。然而，在浪费了时间试图弄清楚为什么**godoc**不起作用之后，我在go 1.13的readme中发现了（页面上未注明日期；由于链接限制以代码形式发布）：

godoc 和 go doc
godoc网络服务器不再包含在主二进制发行版中。要在本地运行godoc网络服务器，请先手动安装它：

go get golang.org/x/tools/cmd/godoc
godoc

所以，它很重要，但我们Go团队懒得把它包含在实际的发行版中——你自己去（动词"go"）想办法解决吧。

更糟糕的是，在v1.18.3中，你实际上不能使用**get，除非你跳过其他一些为了在1.18.3中使用get**而必须的环节。（弄清楚这些晦涩的规则是什么，就留给读者作为练习了）

不过好吧。安装**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

看起来安装成功了。

但它能用吗？不太可能。

作为一个以英语为母语的人，我想我理解这句话（来自Godoc: documenting Go code - The Go Programming Language）的意思，以及当我运行本段中粗体的命令时应该发生什么：

你自己的代码只需拥有如上所述的注释，就能呈现良好的文档。任何安装在$GOROOT/src/pkg内的Go包和任何GOPATH工作空间都已经可以通过godoc的命令行和HTTP接口访问，你可以通过-path标志指定额外的路径进行索引，或者直接在源代码目录中运行**“godoc .”**。

我真傻！这是输出（**sourcedir目录包含一个带有一些文档的.go文件、它的.mod文件，以及两个也包含.go和.mod**文件的子文件夹）：

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

难以置信！（不过，根据痛苦地尝试使用其他面子工程的经验，这非常可信）。

虽然我没有尝试为所有标志设置值，但我确实尝试了具体使用 -http=localhost:6060（结果与上面相同）

-http=localhost:6060 -goroot .（在干净的磁盘上，你可以永远寻道——也就是说，服务器似乎启动了但挂起了）：

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...)

拜托，Go团队。你们能不能靠谱点。

需要说明的是，我愿意阅读手册，无论它写得多么糟糕或不一致，并且我承认我经常有阅读障碍的眼睛-大脑连接有时会看错。但是，一个被吹捧为基础且重要的功能无法开箱即用，这实在太过分了。

这充其量表明发布草率，往坏了说则暗示着无能。 /吐槽

话虽如此，对于那些看完吐槽的人，如果有人解决了这个特定问题，我将非常感谢任何指导。


更多关于Golang中godoc的实用价值探讨的实战教程也可以访问 https://www.itying.com/category-94-b0.html

1 回复

更多关于Golang中godoc的实用价值探讨的实战系列教程也可以访问 https://www.itying.com/category-94-b0.html


godoc确实是一个强大的文档工具，但安装和使用方式在Go 1.13之后发生了变化。以下是具体解决方案：

1. 安装godoc

从Go 1.13开始，godoc需要单独安装：

go install golang.org/x/tools/cmd/godoc@latest

2. 正确运行godoc

godoc现在主要作为Web服务器运行，不再支持直接命令行查看单个包。正确用法：

# 启动本地文档服务器
godoc -http=:6060

# 或者指定GOPATH
godoc -http=:6060 -goroot=$GOPATH

然后在浏览器访问：http://localhost:6060

3. 查看自定义包的文档

对于你的项目，确保在项目根目录运行：

# 进入项目目录
cd C:\GProjects\example\sourcedir

# 启动服务器，godoc会自动索引当前目录
godoc -http=:6060

4. 使用go doc替代命令行查看

对于命令行查看，现在使用go doc命令：

# 查看当前包
go doc

# 查看特定函数
go doc fmt.Printf

# 查看包的所有内容
go doc -all fmt

5. 完整示例

假设有以下项目结构：

myproject/
├── go.mod
└── mypackage/
    └── mycode.go

mycode.go:

// Package mypackage demonstrates documentation
package mypackage

// Add returns the sum of two integers
func Add(a, b int) int {
    return a + b
}

查看文档：

# 命令行查看
go doc mypackage
go doc mypackage.Add

# Web界面查看
cd myproject
godoc -http=:6060
# 访问 http://localhost:6060/pkg/myproject/mypackage/

6. 解决常见问题

如果遇到权限或路径问题，尝试：

# 清理并重新安装
go clean -modcache
go install golang.org/x/tools/cmd/godoc@latest

# 使用完整路径
godoc -http=:6060 -goroot="C:\\GProjects\\example"

godoc的核心价值在于自动从代码注释生成规范的API文档，保持代码和文档同步。虽然安装方式有所变化，但功能依然完整可用。

回到顶部