godoc命令文档

雨点打透心脏的1/2处 2022-09-11 10:24 155阅读 0赞

上一文我们展示了怎么在go文档中插入可测试的代码，那么怎么使用go文档呢。我们找对应的文档来学习下。先来学习下godoc命令。  
下文是对https://pkg.go.dev/golang.org/x/tools/cmd/godoc的翻译。

--------------------

Godoc会提取并为Go程序生成文档。

它会运行一个web服务器并把文档以web网页的形式展示。

godoc -http=:6060

使用：

godoc [flag]

flags有：

-v
    	复杂输出模式
    -timestamps=true
    	在路径列表上展示时间戳
    -index
    	启用标识符和全文搜索索引
    	(如果没有设置 -index 的话，是搜不了文档内容的)
    -index_files=""
    	glob模式指定的索引文件。如果不是空的，就会以排序过的顺序从这些文件中读取索引
    -index_throttle=0.75
    	索引的限速值：设置为0意味着不分配时间给索引器(索引器永远不会终止)，1.0则意味
    	着全速创建索引(在索引创建期间，其他goroutine可能争不到cpu时间)
    -index_interval=0
    	创建索引的间隔时间；0值会设置它为5分钟，负值则只会在启动时建立索引一次。
    -play=false
    	是否启用 playground
    -links=true
    	把标识符链接到他们的声明
    -write_index=false
    	把索引写入文件；文件名必须使用-index_files来指定
    -maxresults=10000
    	能展示的全文搜索结果的最大数量
    	（如果maxresults<=0，不会构建全文索引）
    -notes="BUG"
    	regular expression matching note markers to show
    	(e.g., "BUG|TODO", ".*")
    -goroot=$GOROOT
    	Go的根路径
    -http=addr
    	HTTP服务的地址(例如'127.0.0.1:6060'或者仅':6060')
    -analysis=type,pointer
    	逗号分隔的要展示的分析的列表
    	"type": 展示标识符的resolution，类型信息，方法集，‘实现’，以及静态被调用
    	"pointer": 展示channel两端，调用方和动态被调(明显地更慢)
    	细节见 https://golang.org/lib/godoc/analysis/help.html
    -templates=""
    	路径包含可选的模版文件。如果设置了这个项，对应路径可以提供替代$GOROOT/lib/godoc中文件的模版文件
    -url=path
    	把会为对应路径HTTP请求提供的数据输出到标准输出
    -zip=""
    	指定提供了文件系统的zip文件。为空则不启用

默认的，godoc会看它在$GOROOT和$GOPATH(如果设置了)里头找到的package。可以通过使用-goroot选项，提供另一个$GOROOT来改变这个行为。

当设置了-index选项，就会维护一个搜索索引。这个索引会在启动时被创建。

索引会包含标识符和全文搜索信息(可以通过正则表达式来搜索)。可以通过-maxresults来设置可展示的全文搜索结果的最大数量；如果设置为0，就不会有任何全文结果，仅会有标识符索引而不会创建全文搜索索引。

默认地，godoc会使用系统的GOOS/GOARCH。你可以指定URL参数 "GOOS"和"GOARCH"来为目标系统设置在web页上的输出。

godoc对应web页面的展示模式可以通过"m"URL参数来控制，它接受逗号分隔的flag列表：

> all 为所有声明都展示文档，而不是仅对外公开的那些。  
> methods 展示所有嵌入的方法，而不是仅展示那些未公开的匿名字段  
> src 展示源代码，而不是提取的文档  
> flat 展示平铺(而不是缩紧)的目录列表，也就是全路径

例如，[https://golang.org/pkg/math/big/?m=all][https_golang.org_pkg_math_big_m_all] 会为big package的所有(而不仅是公开的)声明生成文档。

默认的，godoc处理的是底层OS的文件系统上的文件。也可以通过-zip选项提供一个.zip文件，让godoc处理这个zip代表的文件系统。存储在.zip文件中的文件路径必须使用斜杆(’/’)作为路径分割符；并且必须是unrooted的。$GOROOT（或者-goroot）必须被设置到包含Go根路径的.zip文件目录路径。比如，对于一个由以下命令创建的.zip文件：

zip -r go.zip $HOME/go

你可以像这样运行godoc：

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

Godoc文档是使用go/doc package转换为HTML或者文本的；如果想知道提取规则的话，见[https://golang.org/pkg/go/doc/\#ToHTML][https_golang.org_pkg_go_doc_ToHTML]。Godoc也会展示可以被testing包运行的示例代码；约定见[https://golang.org/pkg/testing/\#hdr-Examples][https_golang.org_pkg_testing_hdr-Examples]。见“Godoc：归档Go代码”来学习怎么为godoc写很棒的注释：[https://golang.org/doc/articles/godoc\_documenting\_go\_code.html][https_golang.org_doc_articles_godoc_documenting_go_code.html]。

[https_golang.org_pkg_math_big_m_all]: https://golang.org/pkg/math/big/?m=all
[https_golang.org_pkg_go_doc_ToHTML]: https://golang.org/pkg/go/doc/#ToHTML
[https_golang.org_pkg_testing_hdr-Examples]: https://golang.org/pkg/testing/#hdr-Examples
[https_golang.org_doc_articles_godoc_documenting_go_code.html]: https://golang.org/doc/articles/godoc_documenting_go_code.html