go doc

kiki
Jan 1, 0001 translation

命令

  • go doc 命令可以打印附于 Go 语言程序实体上的文档。可以通过把程序实体的标识符作为该命令的参数来达到查看其文档的目的
  • go doc 可以接受一个参数，指定包/包成员/方法：go doc http.Request
    • go doc 命令根据参数查找代码包或程序实体的顺序：Go 语言根目录（GOROOT 环境变量指定的目录）-> 工作区目录（GOPATH 环境变量包含的目录）。在内部遵循字典序
    • 如果某个工作区目录中的代码包与标准库中的包重名了，那么它是无法被打印出来的。go doc 命令只会打印出第一个匹配的代码包或程序实体的文档
  • go doc 也可以接受两个参数：go doc net/http Request
    • 这是一种更加精细的指定代码包或程序实体的方式
    • 第一个参数的代码包名称必须是完整的导入路径
    • 在给定两个参数时，go doc 会打印出所有匹配的文档，而不是像给定一个参数时那样只打印出第一个匹配的文档。这对于查找只有大小写不同的多个方法（如 New、new）的文档来说非常有用

Go 语言程序实体

  • Go 语言的程序实体，是指变量、常量、函数、结构体以及接口
  • 程序实体的标识符即是代表它们的名称。标识符又分非限定标识符和限定标识符
    • 限定标识符一般用于表示某个代码包中的程序实体或者某个结构体类型中的方法或字段
    • 如：标准库代码包 io 中的名为 EOF 的变量用限定标识符表示即 io.EOF
    • 如：如果有一个 sync.WaitGroup 类型的变量 wg 并且想调用它的 Add 方法，那么可以这样写 wg.Add()。其中，wg.Add 就是一个限定标识符，而后面的 () 则代表了调用操作。

go doc 的参数

参数 描述
-c 区分参数中字母的大小写。默认情况下，命令是大小写不敏感的
-cmd 打印出 main 包中的可导出的程序实体（其名称的首字母大写）的文档。默认情况下，这部分文档是不会被打印出来的
-u 打印出不可导出的程序实体（其名称的首字母小写）的文档。默认情况下，这部分文档是不会被打印出来的

godoc

  • 在 Go1.2 版本之前还支持 go doc 命令，但是之后全部移到了 godoc 这个命令下，需要这样安装 go get golang.org/x/tools/cmd/godoc
  • 在 Go1.5 版本中，go doc 是一个内置的标准命令
  • 命令有两种模式可供选择

命令行模式

  • 不加入 -http 标记：以命令行模式运行。在打印纯文本格式的文档到标准输出后，命令执行就结束了。如 godoc fmt Printf，godoc fmt Printf Println
  • 加 -src 标记：不但可以在文档中查看可导出的程序实体的声明，还可以看到源码。如 godoc -src fmt Printf
  • godoc 命令只能把代码包和程序实体的标识符拆成两个参数。也就是说，godoc 命令不支持前文所述的 go doc 命令的单参数用法
  • 在实际的环境中，可能会遇到一个命令源码文件所产生的可执行文件与代码包重名的情况。比如，标准命令 go 和官方代码包 go。们要明确的告诉 godoc 命令要查看可执行文件 go 的文档，需要在名称前加入 cmd/ 前缀 godoc cmd/go
  • 查看 HTML 格式的文档，就需要加入标记 -html，可以在其中找到一些相应源码的链接地址

Web 服务器模式

  • 加上 -http 标记：以 Web 服务器模式运行。以 Web 页面的形式提供 Go 语言文档
  • godoc -http=:6060 标记 -http 的值 :6060 表示启动的 Web 服务器使用本机的 6060 端口。之后，可通过在浏览器中输入 http://localhost:6060 查看以网页方式展现的 Go 文档
  • 这使得在不方便访问 Go 语言官方站点的情况下也可以查看 Go 语言文档。并且通过本机的 Go 文档 Web 服务，还可以查看所有本机工作区下的代码的文档
  • godoc -http=:9090 -index 使用 -index 标记开启搜索索引。这个索引会在服务器启动时创建并维护。如果不加入此标记，那么无论在 Web 页面还是命令行终端中都无法进行查询操作
go-command

相关