GO 文件筆記
前言
最開始寫 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 doc
import (
"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
這麼好的工具, 那寫文件就更是義不容辭的工作了.
がんばる!!!