前言

最開始寫 GO 的時候, 發現方法的注釋并不支持@param,?@return等參數, 搞得我都不知道該如何給自己的方法寫文檔說明了. 而且網上搜了搜也沒有搜到教程, 甚是郁悶.

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

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

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

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

文檔

經過測試, GO 的文檔格式, 全局變量/常量/函數/結構體/接口/包等等, 聲明格式都一樣, 會讀取對應內容上方緊跟著的注釋內容. 所以就對文檔格式統一介紹即可.

文檔格式

書寫格式

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

/* 這是一個展示文檔作用的包.A 標題這里的標題為首字母大寫, 且后面沒有標點. 如果沒有空行, 則文檔不會換行.B標題二GO 的文檔工具只識別首字母大寫, 不識別中文, 有點難受.開頭空格標識縮進*/ // 同時, 也可以寫成多個單行注釋的形式 package doc

展示形式:

對于包的說明文檔, 因為包下每個文件都有package doc?這段代碼, 如果包下有多個文件都對此包進行了說明, 文檔會將所有說明拼接到一起. 可以單獨建一個doc.go的空文件, 專門用來寫包文檔. (fmt 包就是這么搞的)

全局變量/常量/方法/結構體

全局變量/常量/方法/結構體等內容, 文檔會對其進行歸類, 只要將說明加到其上方即可. 簡單寫個常量看看, 其他同理:

// test const const TestConst = "const"

示例代碼

與寫單元測試類似, 新建一個example_test.go文件. 在其中寫 demo 函數, 會檢測同名以Example開頭的函數:

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

godoc檢測示例代碼:

文檔關鍵字

那 GO 的注釋中有沒有文檔用到的關鍵字呢? 有, 簡單寫幾個.

BUG

可以對 bug 進行描述,?godoc會自動識別并標識出來:

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

Deprecated

已棄用的標識, 這個關鍵字看的太多了, 不過godoc并不會識別這個關鍵字, 主要是編譯器識別.

// Deprecated: 請使用 DocDemoNew 方法

注意

文檔注釋與對應內容之間不能有空行.

godoc只會對公共內容生成文檔, 私有內容不會展示.

---

GO的文檔還有更多, 這里只是簡單的整理一下, 對于之后寫項目基本夠用了, 再也不會在寫 GO 文檔的時候懵逼了. GO 既然已經提供了godoc這么好的工具, 那寫文檔就更是義不容辭的工作了.

がんばる!!!

創作挑戰賽新人創作獎勵來咯，堅持創作打卡瓜分現金大獎

總結

以上是生活随笔為你收集整理的GO 文档笔记的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。