Go语言之Doc 文档

2025-01-13 技术教程

对于协作开发或者代码共享来说，文档是一个可以帮助开发者快速了解以及使用这些代码的一个教程，文档越全面、越详细，入门越快，效率也会更高。

在Go语言中，Go为我们提供了快速生成文档以及查看文档的工具，让我们可以很容易地编写查看文档。

Go提供了两种查看文档的方式：一种是使用go doc命令在终端查看。这种适用于使用VIM等工具在终端开发的人员，他们不用离开终端，既可以查看想查看的文档，又可以编码。

第二种方式，是使用浏览器查看的方式。通过godoc命令可以在本机启动一个Web服务，我们可以通过打开浏览器，访问这个服务来查看我们的Go文档。

从终端查看文档

这种方式适用于在终端开发的人员，他们一般不想离开终端，查完即可继续编码，这时候使用go doc命令是很不错的选择。

hellogohelpdocusage:godoc[-u][-c][package|[package.]symbol[.method]]Docprintsthedocumentationcommentsassociatedwiththeitemidentifiedbyitsarguments(apackage,const,func,type,var,ormethod)followedbyaone-linesummaryofeachofthefirst-levelitems"under"thatitem(package-leveldeclarationsforapackage,methodsforatype,etc.).Flags:-cRespectcasewhenmatchingsymbols.-cmdTreatacommand(packagemain)likearegularpackage.Otherwisepackagemain'sexportedsymbolsarehiddenwhenshowingthepackage'stop-leveldocumentation.-uShowdocumentationforunexportedaswellasexportedsymbolsandmethods.

从以上可以看出，go doc的使用比较简单，接收的参数是包名，或者是包里的结构体、方法等。如果我们不输入任何参数，那么显示的是当前目录的文档，下面看个例子。

/*提供的常用库，有一些常用的方法，方便使用*/packagelib//一个加法实现//返回a+b的值funcAdd(a,bint)int{returna+b}

libgodocpackagelib//import"flysnow.org/hello/lib"提供的常用库，有一些常用的方法，方便使用funcAdd(a,bint)int

在当前目录执行go doc，输出了当前目录下的文档信息。

除此之外，我们还可以指定一个包，这样就能列出当前这个包的信息，它包括文档、方法、结构体等。

libgodocjsonpackagejson//import"encoding/json"PackagejsonimplementsencodinganddecodingofJSONasdefinedinRFC4627.ThemappingbetweenJSONandGovaluesisdescribedinthedocumentationfortheMarshalandUnmarshalfunctions.See"JSONandGo"foranintroductiontothispackage:https://golang.org/doc/articles/json_and_go.htmlfuncCompact(dst*bytes.Buffer,src[]byte)errorfuncHTMLEscape(dst*bytes.Buffer,src[]byte)funcIndent(dst*bytes.Buffer,src[]byte,prefix,indentstring)errorfuncMarshal(vinterface{})([]byte,error)funcMarshalIndent(vinterface{},prefix,indentstring)([]byte,error)funcUnmarshal(data[]byte,vinterface{})errortypeDecoderstruct{...}funcNewDecoder(rio.Reader)*DecodertypeDelimrunetypeEncoderstruct{...}funcNewEncoder(wio.Writer)*EncodertypeInvalidUTF8Errorstruct{...}typeInvalidUnmarshalErrorstruct{...}typeMarshalerinterface{...}typeMarshalerErrorstruct{...}typeNumberstringtypeRawMessage[]bytetypeSyntaxErrorstruct{...}typeTokeninterface{}typeUnmarshalFieldErrorstruct{...}typeUnmarshalTypeErrorstruct{...}typeUnmarshalerinterface{...}typeUnsupportedTypeErrorstruct{...}typeUnsupportedValueErrorstruct{...}

以上是我们以json包为例，查看该包的文档。从中我们可以看到它有一个名为Decoder的结构体，我们进一步查看这个结构体的文档。

libgodocjson.Decoderpackagejson//import"encoding/json"typeDecoderstruct{//Hasunexportedfields.}ADecoderreadsanddecodesJSONvaluesfromaninputstream.funcNewDecoder(rio.Reader)*Decoderfunc(dec*Decoder)Buffered()io.Readerfunc(dec*Decoder)Decode(vinterface{})errorfunc(dec*Decoder)More()boolfunc(dec*Decoder)Token()(Token,error)func(dec*Decoder)UseNumber()

现在我们看到这个Decoder有很多方法，进一步查看这些方法的文档，比如Decode。

libgodocjson.Decoder.Decodefunc(dec*Decoder)Decode(vinterface{})errorDecodereadsthenextJSON-encodedvaluefromitsinputandstoresitinthevaluepointedtobyv.SeethedocumentationforUnmarshalfordetailsabouttheconversionofJSONintoaGovalue.

go doc的使用就是这样，一步步，缩小范围，查看想看的那些包、结构体、接口或者函数方法的文档。

在线浏览文档

go doc终端查看的方式，虽然也很便捷，不过效率不高，并且没有查看细节以及进行跳转，为此Go为我们提供了基于浏览器使用的网页方式进行浏览API文档。我们只需要点点鼠标，就可以查看了。还可以在方法、包等之间进行跳转，更简洁方便。

要想启动一个Web在线API文档服务很简单，使用godoc就可以了。

libgodoc-http=:6060

后面的http是要指定Web服务监听的IP和Port，运行后，我们就可以打开浏览器，输入http://127.0.0.1:6060进行访问了。你会发现，打开的页面和GoLang的官方网站一样。没错，这其实就是官网的一个拷贝，但是包的文档http://127.0.0.1:6060/pkg/会和官网不一样,你自己启动的这个服务，是基于你电脑上GOROOT和GOPATH这两个路径下的所有包生成的文档，会比官网里的只是标准库的文档要多。

在线浏览API文档非常方便，只需要鼠标点击就可以了；也可以点击蓝色的超链接在方法、结构、接口以及包等之间跳转；还可以查看对应的源代码、示例代码，很方便，我们经常用的也是这个在线浏览方式。

生成自己的文档

Go文档工具，还有一个亮点，就是可以支持开发人员自己写代码，只要开发者按照一定的规则，就可以自动生成文档了。

在我们编码中，文档就是注释，Go语言采用了和C、Java差不多的注释风格。一种是双斜线的方式，一种是斜线和星号的方式。

/*提供的常用库，有一些常用的方法，方便使用*/packagelib//一个加法实现//返回a+b的值funcAdd(a,bint)int{returna+b}

这还是我们刚刚的那个例子，例子中文档的编写有两种风格。想要为哪些标识符生成文档，就在哪些标识符之前，使用注释的方式，加入到代码中即可。

现在我们不管是用go doc，还是godoc都可以看到我们刚刚注释的文档了。

添加文档示例

我们在看很多官方API文档的时候，可以在文档里看到一些例子，这些例子会告诉我们怎么使用API，以及这个例子打印的输出是什么。我觉得这个非常好，这样看函数文档看不懂的人，就可以参考这个例子。那么对于我们自己写的API，怎么给API文档添加示例代码呢？

这里我参考了官方的源代码，总结了测试了一下，发现可行，这里分享一下。

示例代码必须单独存放在一个文件中，文件名字为example_test.go。

在这个go文件里，定义一个名字为Example的函数，参数为空。