Golang中的godoc使用簡介(推薦)
go doc簡介
Godoc是go語言的文檔化工具,類似于文檔化工具godoc,類似于Python的Docstring和Java的Javadoc
Godoc通過解析包含注釋的Go代碼來生成HTML或文本類型的文檔。
Golang中的godoc使用簡介
學(xué)習(xí)go語法的同時為了方便查看對應(yīng)的文檔,不同的Go版本會有一些改動,所以,使用本地Go源碼生成的文檔顯然更精確。
go在1.13之前是自帶godoc的,之后的版本需要自行安裝。
go get -u golang.org/x/tools/cmd/godoc
// 并沒有自動安裝go install golang.org/x/tools/cmd/godoc
// 手動安裝
> godoc -h usage: godoc -http=localhost:6060 -goroot string Go root directory (default "D:\\Go") -http string HTTP service address (default "localhost:6060") -index enable search index -index_files string glob pattern specifying index files; if not empty, the index is read from these files in sorted order -index_interval duration interval of indexing; 0 for default (5m), negative to only index once at startup -index_throttle float index throttle value; 0.0 = no time allocated, 1.0 = full throttle (default 0.75) -links link identifiers to their declarations (default true) -maxresults int maximum number of full text search results shown (default 10000) -notes string regular expression matching note markers to show (default "BUG") -play enable playground -templates string load templates/JS/CSS from disk in this directory -timestamps show timestamps with directory listings -url string print HTML for named URL -v verbose mode -write_index write index to a file; the file name must be specified with -index_files -zip string zip file providing the file system to serve; disabled if empty
進(jìn)入到Go源碼目錄,D:\Go\src
godoc -http=:6060
掃描文件需要時間,啟動之后有時候還要等一會。
訪問瀏覽器 http://localhost:6060/
訪問指定的包http://localhost:6060/pkg/fmt/
http://localhost:6060/pkg/archive/tar/
可以通過godoc -url "http://localhost:6060/pkg/" > doc.html
導(dǎo)出為靜態(tài)的html單個文件,但是這個體驗很差。
如果我們要查看一個第三方包的文檔,比如 github.com/julienschmidt/httprouter
首先要進(jìn)入它的源碼目錄godoc -http=localhost:6060
第一部分依然是 Go Standard library,第二部分 Third party 才是 httprouter 的文檔
如果我們要查看某個項目的文檔也可以使用這種方式,然后我就發(fā)現(xiàn)我們自己寫的項目大多沒有什么注釋,于是這就牽涉到注釋的規(guī)范。
注釋使用//
加一個空格并且要緊跟著被注釋對象的上方。
首先需要給package加上注釋,說明此包的作用,例如
// Package bufio implements buffered I/O. It wraps an io.Reader or io.Writer // object, creating another object (Reader or Writer) that also implements // the interface but provides buffering and some help for textual I/O. package bufio
同一目錄下的包可以由很多個文件組成,如果每個文件都有對package進(jìn)行注釋的話,godoc會自動將所有注釋"按照文件名的字母數(shù)序"進(jìn)行合并
在無效注釋中以BUG(who)開頭的注釋, 將被識別為已知bug, 顯示在bugs區(qū)域
// BUG(who): 因為前面有BUG(who)這個關(guān)鍵字,所以這句注釋就算沒有緊跟關(guān)鍵字不會被隱藏掉
關(guān)于DEPRECATED
棄用
// Time returns an int64 unix timestamp in milliseconds of the snowflake ID time // DEPRECATED: the below function will be removed in a future release. func (f ID) Time() int64 { return (int64(f) >> timeShift) + Epoch }
在注釋符要縮進(jìn)的話,第二行注釋符后面的空格要比上一行的空格多一個
example: // 123 // 123
關(guān)于 go doc xxx
主要用來在終端上查看某個包的文檔,它也是通過掃描包內(nèi)的一些注釋,然后格式化輸出,但很少這么用。
> go doc fmt package fmt // import "fmt" Package fmt implements formatted I/O with functions analogous to C's printf and scanf. The format 'verbs' are derived from C's but are simpler. Printing The verbs: General: %v the value in a default format when printing structs, the plus flag (%+v) adds field names %#v a Go-syntax representation of the value %T a Go-syntax representation of the type of the value %% a literal percent sign; consumes no value ... ...
go doc約定規(guī)則
godoc
Go的注釋規(guī)則很簡單,為類型,變量,常量,函數(shù)或包編寫注釋時,直接在這些聲明前編寫普通形式的注釋,中間不留空行即可。Godoc將這些注釋與后面的聲明連接到一起,達(dá)到文檔化的目的。
1.注釋符// 后加空格
// 這是一行注釋 package main
2.注釋緊鄰關(guān)鍵字行寫,否則不會被識別
// 不會被識別 // 會被識別 package main // 不會被識別 // 會被識別1 // 會被識別2 func main(){ }
3.注釋行的數(shù)量最好不要超過3行
4.已知bug注釋:BUG(who)
godoc的輸出將忽略那些與頂層聲明不相鄰的注釋,只有一個例外,那就是以BUG(who)開頭的注釋。這些注釋將被識別為已知的bug,并包含在文檔的BUGS區(qū)。
// 注釋 package main // BUG(who) //會被識別,放入文檔的Bugs區(qū) const a = 8
使用命令
首先在命令行進(jìn)入所需要執(zhí)行的.go文檔目錄
例:我的test.go放在C:/GoProject/src/test/ 目錄下
需要在命令行進(jìn)入C:/GoProject/src/test/
然后執(zhí)行命令
godoc -http=:6060 ? ? //6060是godoc提供的默認(rèn)端口
在瀏覽器輸入 localhost:6060,即可進(jìn)入godoc的網(wǎng)站,查看自己的文檔需要在地址欄輸入路徑 localhost:6060/pkg/test
到此這篇關(guān)于Golang中的godoc使用簡介的文章就介紹到這了,更多相關(guān)go語言godoc使用內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家!
相關(guān)文章
一文帶你搞懂Golang結(jié)構(gòu)體內(nèi)存布局
結(jié)構(gòu)體在Go語言中是一個很重要的部分,在項目中會經(jīng)常用到。這篇文章主要帶大家看一下結(jié)構(gòu)體在內(nèi)存中是怎么分布的?通過對內(nèi)存布局的了解,可以幫助我們寫出更優(yōu)質(zhì)的代碼。感興趣的小伙伴們可以參考借鑒,希望對大家能有所幫助2022-10-10利用golang進(jìn)行OpenCV學(xué)習(xí)和開發(fā)的步驟
目前,OpenCV逐步成為一個通用的基礎(chǔ)研究和產(chǎn)品開發(fā)平臺,下面這篇文章主要給大家介紹了關(guān)于利用golang進(jìn)行OpenCV學(xué)習(xí)和開發(fā)的相關(guān)資料,文中通過示例代碼介紹的非常詳細(xì),需要的朋友可以參考下2018-09-09