《Go語言實戰(zhàn)》筆記(三) | Go Doc 文檔

《Go語言實戰(zhàn)》讀書筆記，未完待續(xù)，歡迎關(guān)注公眾號flysnow_org，第一時間看后續(xù)筆記。

對于協(xié)作開發(fā)或者代碼共享來說，文檔是一個可以幫助開發(fā)者快速了解以及使用這些代碼的一個教程，文檔越全面，越詳細(xì)，入門越快，效率也會更高。

在Go語言中，Go為我們提供了快速生成文檔以及查看文檔的工具，讓我們可以很容易的編寫查看文檔。

Go提供了兩種查看文檔的方式，一種是使用go doc命令在終端查看，這種適用于使用VIM等工具在終端開發(fā)的人員，它們不用離開終端，既可以查看想查看的文檔，又可以編碼。

第二種方式，是使用瀏覽器查看的方式，通過godoc命令可以在本機啟動一個web服務(wù)，我們可以通過打開瀏覽器，訪問這個服務(wù)來查看我們的Go文檔。

從終端查看文檔

這種方式適用于在終端開發(fā)的，它們一般不像離開終端，查完即可繼續(xù)編碼，這時候使用go doc命令是很不錯的選擇。

???hello?go?help?doc usage:?go?doc?[-u]?[-c]?[package|[package.]symbol[.method]] Doc?prints?the?documentation?comments?associated?with?the?item?identified?by?its arguments?(a?package,?const,?func,?type,?var,?or?method)?followed?by?a?one-line summary?of?each?of?the?first-level?items?"under"?that?item?(package-level declarations?for?a?package,?methods?for?a?type,?etc.). Flags: ????-c ????????Respect?case?when?matching?symbols. ????-cmd ????????Treat?a?command?(package?main)?like?a?regular?package. ????????Otherwise?package?main's?exported?symbols?are?hidden ????????when?showing?the?package's?top-level?documentation. ????-u ????????Show?documentation?for?unexported?as?well?as?exported ????????symbols?and?methods.

從以上可以看出，go doc的使用比較簡單，接收的參數(shù)是包名，或者以包里的結(jié)構(gòu)體、方法等。如果我們不輸入任何參數(shù)，那么顯示的是當(dāng)前目錄的文檔，下面看個例子。

/* ?提供的常用庫，有一些常用的方法，方便使用 ?*/package?lib//?一個加法實現(xiàn)//?返回a+b的值func?Add(a,b?int)?int?{????return?a+b }

???lib?go?doc package?lib?//?import?"flysnow.org/hello/lib"提供的常用庫，有一些常用的方法，方便使用 func?Add(a,?b?int)?int

在當(dāng)前目錄執(zhí)行g(shù)o doc，輸出了當(dāng)前目錄下的文檔信息。

除此之外，我們還可以指定一個包，就可以列出當(dāng)前這個包的信息，著包括文檔、方法、結(jié)構(gòu)體等。

???lib?go?doc?json package?json?//?import?"encoding/json"Package?json?implements?encoding?and?decoding?of?JSON?as?defined?in?RFC 4627.?The?mapping?between?JSON?and?Go?values?is?described?in?the documentation?for?the?Marshal?and?Unmarshal?functions. See?"JSON?and?Go"?for?an?introduction?to?this?package: https://golang.org/doc/articles/json_and_go.html func?Compact(dst?*bytes.Buffer,?src?[]byte)?error func?HTMLEscape(dst?*bytes.Buffer,?src?[]byte) func?Indent(dst?*bytes.Buffer,?src?[]byte,?prefix,?indent?string)?error func?Marshal(v?interface{})?([]byte,?error) func?MarshalIndent(v?interface{},?prefix,?indent?string)?([]byte,?error) func?Unmarshal(data?[]byte,?v?interface{})?errortype?Decoder?struct{?...?} ????func?NewDecoder(r?io.Reader)?*Decodertype?Delim?runetype?Encoder?struct{?...?} ????func?NewEncoder(w?io.Writer)?*Encodertype?InvalidUTF8Error?struct{?...?} ????type?InvalidUnmarshalError?struct{?...?} ????type?Marshaler?interface{?...?} ????type?MarshalerError?struct{?...?} ????type?Number?stringtype?RawMessage?[]byte ????type?SyntaxError?struct{?...?} ????type?Token?interface{} ????type?UnmarshalFieldError?struct{?...?} ????type?UnmarshalTypeError?struct{?...?} ????type?Unmarshaler?interface{?...?} ????type?UnsupportedTypeError?struct{?...?} ????type?UnsupportedValueError?struct{?...?}

以上是我們以json包為例，查看該包的文檔，從中我們可以看到它有一個名為Decoder的結(jié)構(gòu)體，我們進一步查看這個結(jié)構(gòu)體的文檔。

???lib?go?doc?json.Decoder package?json?//?import?"encoding/json"type?Decoder?struct?{ ????//?Has?unexported?fields. } ????A?Decoder?reads?and?decodes?JSON?values?from?an?input?stream. func?NewDecoder(r?io.Reader)?*Decoder func?(dec?*Decoder)?Buffered()?io.Reader func?(dec?*Decoder)?Decode(v?interface{})?error func?(dec?*Decoder)?More()?bool func?(dec?*Decoder)?Token()?(Token,?error) func?(dec?*Decoder)?UseNumber()

現(xiàn)在我們看到這個Decoder有很多方法,進一步查看這些方法的文檔，比如Decode。

???lib?go?doc?json.Decoder.Decode???? func?(dec?*Decoder)?Decode(v?interface{})?error ????Decode?reads?the?next?JSON-encoded?value?from?its?input?and?stores?it?in?the ????value?pointed?to?by?v. ????See?the?documentation?for?Unmarshal?for?details?about?the?conversion?of?JSON ????into?a?Go?value.

go doc使用就是這樣，一步步，縮小范圍，查看想看的那些包、結(jié)構(gòu)體、接口或者函數(shù)方法的文檔。

在線瀏覽文檔

go doc終端查看的方式，雖然也很便捷，不過效率不高，并且沒有查看細(xì)節(jié)以及進行跳轉(zhuǎn)，為此Go為我們提供了基于瀏覽器使用的網(wǎng)頁方式進行瀏覽API 文檔，我們只用點點鼠標(biāo)，就可以查看了，還可以在方法、包等之間進行跳轉(zhuǎn)，更簡潔方便。

要想啟動一個Web在線API文檔服務(wù)很簡單，使用godoc就可以了。

???lib?godoc?-http=:6060

后面的http是要指定Web服務(wù)監(jiān)聽的IP和Port，運行后，我們就可以打開瀏覽器，輸入http://127.0.0.1:6060進行訪問了，你會發(fā)現(xiàn)打開的頁面，和GoLang的官方網(wǎng)站一樣，沒錯，這個其實就是官網(wǎng)的一個拷貝，但是包的文檔http://127.0.0.1:6060/pkg/會和官網(wǎng)不一樣,你自己啟動的這個服務(wù)，是基于你電腦上GOROOT和GOPATH這兩個路徑下的所有包生成的文檔，會比官網(wǎng)只是標(biāo)準(zhǔn)庫的文檔要多。

在線瀏覽API文檔非常方便，只需要鼠標(biāo)點擊就可以了，也可以點擊藍(lán)色的超鏈接在方法、結(jié)構(gòu)、接口以及包等之間跳轉(zhuǎn)，還可以查看對應(yīng)的源代碼，示例代碼，很方便，我們經(jīng)常用的也是這個在線瀏覽方式。

生成自己的文檔

Go文檔工具，還有一個亮點，就是可以支持開發(fā)人員自己寫的代碼，只要開發(fā)者按照一定的規(guī)則，就可以自動生成文檔了。

在我們編碼中，文檔就是注釋，Go語言采用了和C、Java差不多的注釋風(fēng)格。一種是雙斜線的方式，一種是斜線和星號的方式。

/* ?提供的常用庫，有一些常用的方法，方便使用 ?*/package?lib//?一個加法實現(xiàn)//?返回a+b的值func?Add(a,b?int)?int?{????return?a+b }

這還是我們剛剛那個例子，例子中文檔的編寫的兩種風(fēng)格。想要為哪些標(biāo)識符生車文檔，就在哪些標(biāo)識符之前，使用注釋的方式，加入到代碼中即可。

現(xiàn)在我們不管是用go doc，還是godoc都可以看到我們剛剛注釋的文檔了。

添加文檔示例

我們在看很多官方API文檔的時候，可以在文檔里看到一些例子，這些例子會告訴我們怎么使用API，以及這個例子打印的輸出是什么，我覺得這個非常好，這樣看函數(shù)文檔看不懂的，可以參考這個例子，那么對于我們自己寫的API，怎么給API文檔添加示例代碼呢？

這里我參考了官方的源代碼，總結(jié)了測試了一下，發(fā)現(xiàn)可行，這里分享一下。

示例代碼必須單獨存放在一個文件中，文件名字為example_test.go。

在這個go文件里，定義一個名字為Example的函數(shù)，參數(shù)為空

示例的輸出采用注視的方式，以//Output:開頭，另起一行，每行輸出占一行。

說了這三個規(guī)則，下面通過一個例子更直觀的了解。

package?libimport?"fmt"func?Example()?{ ????sum:=Add(1,2) ????fmt.Println("1+2=",sum)????//Output: ????//1+2=3}

這就是為剛剛那個Add函數(shù)寫的示例代碼，我們運行g(shù)odoc就可以看到結(jié)果了。

Go的文檔工具非常強大，更多功能，我們可以使用幫助命令查看。這里再推薦一個比較不錯的第三方的API文檔網(wǎng)站，收錄了包括官方在內(nèi)的很多Go庫，可以直接跳轉(zhuǎn)，關(guān)聯(lián)源代碼，非常方便。https://gowalker.org/

《Go語言實戰(zhàn)》讀書筆記，未完待續(xù)，歡迎關(guān)注公眾號flysnow_org，第一時間看后續(xù)筆記。

本文轉(zhuǎn)載自異步社區(qū)。

JSON Go API

版權(quán)聲明：本文內(nèi)容由網(wǎng)絡(luò)用戶投稿，版權(quán)歸原作者所有，本站不擁有其著作權(quán)，亦不承擔(dān)相應(yīng)法律責(zé)任。如果您發(fā)現(xiàn)本站中有涉嫌抄襲或描述失實的內(nèi)容，請聯(lián)系我們jiasou666@gmail.com 處理，核實后本網(wǎng)站將在24小時內(nèi)刪除侵權(quán)內(nèi)容。

版權(quán)聲明：本文內(nèi)容由網(wǎng)絡(luò)用戶投稿，版權(quán)歸原作者所有，本站不擁有其著作權(quán)，亦不承擔(dān)相應(yīng)法律責(zé)任。如果您發(fā)現(xiàn)本站中有涉嫌抄襲或描述失實的內(nèi)容，請聯(lián)系我們jiasou666@gmail.com 處理，核實后本網(wǎng)站將在24小時內(nèi)刪除侵權(quán)內(nèi)容。