前言

最開(kāi)始寫 GO 的時(shí)候, 發(fā)現(xiàn)方法的注釋并不支持@param, @return等參數(shù), 搞得我都不知道該如何給自己的方法寫文檔說(shuō)明了. 而且網(wǎng)上搜了搜也沒(méi)有搜到教程, 甚是郁悶.

今天找到了GO內(nèi)置的文檔工具: godoc. (我用的1.14.3版本貌似不是自帶工具了, 需要安裝(配置代理): go get golang.org/x/tools/cmd/godoc)

運(yùn)行命令: godoc -http=:8888. 可以直接在本地瀏覽器訪問(wèn)8888端口, 查看這個(gè)運(yùn)行在本地的文檔服務(wù): localhost:8888. 能夠看到所有官方包的文檔. 而這些文檔內(nèi)容都是從官方代碼包中讀取的.

這個(gè)文檔工具不光能夠檢測(cè)官方文檔, 還能夠檢測(cè)自己的項(xiàng)目, 只要將項(xiàng)目配置到GOPATH下即可.

既然人家官方代碼能生成文檔, 那就說(shuō)明是有文檔生成格式的呀. 既然我不知道如何寫文檔, 抄官方的樣式不就行了么? nice. 以下是我多處借鑒后, 總結(jié)的 GO 文檔書(shū)寫規(guī)則.

文檔

經(jīng)過(guò)測(cè)試, GO 的文檔格式, 全局變量/常量/函數(shù)/結(jié)構(gòu)體/接口/包等等, 聲明格式都一樣, 會(huì)讀取對(duì)應(yīng)內(nèi)容上方緊跟著的注釋內(nèi)容. 所以就對(duì)文檔格式統(tǒng)一介紹即可.

文檔格式

書(shū)寫格式

文檔的書(shū)寫影響其展示形式, 如下所示:

/*這是一個(gè)展示文檔作用的包.A 標(biāo)題這里的標(biāo)題為首字母大寫, 且后面沒(méi)有標(biāo)點(diǎn).如果沒(méi)有空行, 則文檔不會(huì)換行.B標(biāo)題二GO 的文檔工具只識(shí)別首字母大寫, 不識(shí)別中文, 有點(diǎn)難受. 開(kāi)頭空格標(biāo)識(shí)縮進(jìn) */// 同時(shí), 也可以寫成多個(gè)單行注釋的形式package doc

展示形式:

對(duì)于包的說(shuō)明文檔, 因?yàn)榘旅總€(gè)文件都有package doc 這段代碼, 如果包下有多個(gè)文件都對(duì)此包進(jìn)行了說(shuō)明, 文檔會(huì)將所有說(shuō)明拼接到一起. 可以單獨(dú)建一個(gè)doc.go的空文件, 專門用來(lái)寫包文檔. (fmt 包就是這么搞的)

全局變量/常量/方法/結(jié)構(gòu)體

全局變量/常量/方法/結(jié)構(gòu)體等內(nèi)容, 文檔會(huì)對(duì)其進(jìn)行歸類, 只要將說(shuō)明加到其上方即可. 簡(jiǎn)單寫個(gè)常量看看, 其他同理:

// test constconst TestConst = "const"

示例代碼

與寫單元測(cè)試類似, 新建一個(gè)example_test.go文件. 在其中寫 demo 函數(shù), 會(huì)檢測(cè)同名以Example開(kāi)頭的函數(shù):

package docimport ( "fmt")func ExampleDemoTest() { DemoTest() // OutPut: // 沒(méi)有返回值}// 多個(gè) demo, 下劃線后拼單詞或數(shù)字func ExampleDemoTest_2() { DemoTest()}// 包 demo, 對(duì)于沒(méi)有指定方法的, 會(huì)識(shí)別為這個(gè)包的例子func Example() { fmt.Println("aaaa") // OutPut: // none}// 包 demo2func Example_2() { fmt.Println("bbb")}

godoc檢測(cè)示例代碼:

文檔關(guān)鍵字

那 GO 的注釋中有沒(méi)有文檔用到的關(guān)鍵字呢? 有, 簡(jiǎn)單寫幾個(gè).

BUG

可以對(duì) bug 進(jìn)行描述, godoc會(huì)自動(dòng)識(shí)別并標(biāo)識(shí)出來(lái):

// BUG(hujing): 對(duì) bug 的描述信息

Deprecated

已棄用的標(biāo)識(shí), 這個(gè)關(guān)鍵字看的太多了, 不過(guò)godoc并不會(huì)識(shí)別這個(gè)關(guān)鍵字, 主要是編譯器識(shí)別.

// Deprecated: 請(qǐng)使用 DocDemoNew 方法

注意

文檔注釋與對(duì)應(yīng)內(nèi)容之間不能有空行.

godoc只會(huì)對(duì)公共內(nèi)容生成文檔, 私有內(nèi)容不會(huì)展示.

---

GO的文檔還有更多, 這里只是簡(jiǎn)單的整理一下, 對(duì)于之后寫項(xiàng)目基本夠用了, 再也不會(huì)在寫 GO 文檔的時(shí)候懵逼了. GO 既然已經(jīng)提供了godoc這么好的工具, 那寫文檔就更是義不容辭的工作了.

がんばる!!!

總結(jié)

以上是生活随笔為你收集整理的go 查看全局安装了哪些包_GO 文档笔记的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。

如果覺(jué)得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。