注意，要將項目 zz (文件夾）放在GOPATH指定的某個目錄的src下。如GOPATH爲：GOPATH="/root/go:/data/code"
則可以將目錄 zz 放到 /data/code/src下面！！
b.go
/*
簡易計算器計算自定義包
*/
package zz
// 一種實現兩個整數相加的函數，
// 返回值爲兩整數相加之和
func Add(a, b int) int {
return a + b
}
// 一種實現兩個整數相減的函數，
// 返回值爲兩整數相減之差
func Sub(a, b int) int {
return a - b
}
// 一種實現兩個整數相乘的函數，
// 返回值爲兩整數相乘之積
func Mul(a, b int) int {
return a * b
}
// 一種實現兩個整數相除的函數，
// 返回值爲兩整數相除之商
func Div(a, b int) int {
if b == 0 {
panic("divide by zero")
}
return a / b
}
b_test.go
package zz
import (
"fmt"
)
func ExampleAdd() {
result := Add(4, 2)
fmt.Println("4 + 2 =", result)
// Output:
// 4 + 2 = 6
}
func ExampleSub() {
result := Sub(4, 2)
fmt.Println("4 - 2 =", result)
// Output:
// 4 - 2 = 2
}
func ExampleMul() {
result := Mul(4, 2)
fmt.Println("4 * 2 =", result)
// Output:
// 4 * 2 = 8
}
func ExampleDiv() {
result := Div(4,2)
fmt.Println("4 / 2 =", result)
// Output:
// 4 / 2 = 2
}
~
原文：https://blog.csdn.net/whatday/article/details/103293838
----------------------------
Go語言項目十分重視代碼的文檔，在軟件設計中，文檔對於軟件的可維護和易使用具有重大的影響。因此，文檔必須是書寫良好並準確的，與此同時它還需要易於書寫和維護。
Go語言註釋
Go語言中註釋一般分爲兩種，分別是單行註釋和多行註釋
- 單行註釋是以
//開頭的註釋，可以出現在任何地方。 - 多行註釋也叫塊註釋，以
/*開頭，以*/結尾，不可以嵌套使用，一般用於包的文檔描述或註釋成塊的代碼片段。
每一個 package 都應該有相關注釋，在 package 語句之前的註釋內容將被默認認爲是這個包的文檔， package 的註釋應該提供一些相關信息並對整體功能做簡要的介紹。
在日常開發過程中，可以使用go doc和godoc命令生成代碼的文檔。
go doc
go doc 命令打印Go語言程序實體上的文檔。可以使用參數來指定程序實體的標識符。
Go語言程序實體是指變量、常量、函數、結構體以及接口。
程序實體標識符就是程序實體的名稱。
go doc 用法
go doc [-u] [-c] [package|[package.]symbol[.methodOrField]]
可用的標識：
| 標識 | 說明 |
|---|---|
| -all | 顯示所有文檔 |
| -c | 匹配程序實體時，大小寫敏感 |
| -cmd | 將命令（main包）視爲常規程序包，如果要顯示main包的doc，請指定這個標識 |
| -src | 顯示完整源代碼 |
| -u | 顯示未導出的程序實體 |
示例
輸出指定 package ，指定類型，指定方法的註釋
$ go doc sync.WaitGroup.Add
輸出指定 package ，指定類型的所有程序實體，包括未導出的
$ go doc -u -all sync.WaitGroup
輸出指定 package 的所有程序實體（非所有詳細註釋）
$ go doc -u sync
godoc
godoc命令主要用於在無法聯網的環境下，以web形式，查看Go語言標準庫和項目依賴庫的文檔。
在 go 1.12 之後的版本中，godoc不再做爲go編譯器的一部分存在。依然可以通過go get命令安裝：
go get -u -v golang.org/x/tools/cmd/godoc
國內的安裝方法
-
mkdir -p $GOPATH/src/golang.org/x
-
cd $GOPATH/src/golang.org/x
-
git clone https://github.com/golang/tools.git
-
cd tools/cmd/godoc
-
go install
-
ls -alh $GOPATH/bin
通過終端查看文檔
-
go doc命令
-
$ go doc help
-
usage: go doc [-u] [-c] [package|[package.]symbol[.method]]
-
-
查看系統log包信息
-
linux@ubuntu:/usr/local/go/src/log$ go doc
-
package log // import "log"
-
-
Package log implements a simple logging package. It defines a type, Logger,
-
with methods for formatting output. It also has a predefined 'standard'
-
Logger accessible through helper functions Print[f|ln], Fatal[f|ln], and
-
Panic[f|ln], which are easier to use than creating a Logger manually. That
-
logger writes to standard error and prints the date and time of each logged
-
message. Every log message is output on a separate line: if the message
-
being printed does not end in a newline, the logger will add one. The Fatal
-
functions call os.Exit(1) after writing the log message. The Panic functions
-
call panic after writing the log message.
-
-
const Ldate = 1 << iota ...
-
func Fatal(v ...interface{})
-
func Fatalf(format string, v ...interface{})
-
func Fatalln(v ...interface{})
-
func Flags() int
-
func Output(calldepth int, s string) error
-
func Panic(v ...interface{})
-
func Panicf(format string, v ...interface{})
-
func Panicln(v ...interface{})
-
func Prefix() string
-
func Print(v ...interface{})
-
func Printf(format string, v ...interface{})
-
func Println(v ...interface{})
-
func SetFlags(flag int)
-
func SetOutput(w io.Writer)
-
func SetPrefix(prefix string)
-
type Logger struct{ ... }
-
func New(out io.Writer, prefix string, flag int) *Logger
-
-
查看系統log包中Fatal方法
-
linux@ubuntu:/usr/local/go/src/log$ go doc log.Fatal
-
func Fatal(v ...interface{})
-
Fatal is equivalent to Print() followed by a call to os.Exit(1).
-
-
查看系統log包中Logger結構
-
linux@ubuntu:/usr/local/go/src/log$ go doc Logger
-
type Logger struct {
-
// Has unexported fields.
-
}
-
A Logger represents an active logging object that generates lines of output
-
to an io.Writer. Each logging operation makes a single call to the Writer's
-
Write method. A Logger can be used simultaneously from multiple goroutines;
-
it guarantees to serialize access to the Writer.
-
-
-
func New(out io.Writer, prefix string, flag int) *Logger
-
func (l *Logger) Fatal(v ...interface{})
-
func (l *Logger) Fatalf(format string, v ...interface{})
-
func (l *Logger) Fatalln(v ...interface{})
-
func (l *Logger) Flags() int
-
func (l *Logger) Output(calldepth int, s string) error
-
func (l *Logger) Panic(v ...interface{})
-
func (l *Logger) Panicf(format string, v ...interface{})
-
func (l *Logger) Panicln(v ...interface{})
-
func (l *Logger) Prefix() string
-
func (l *Logger) Print(v ...interface{})
-
func (l *Logger) Printf(format string, v ...interface{})
-
func (l *Logger) Println(v ...interface{})
-
func (l *Logger) SetFlags(flag int)
-
func (l *Logger) SetOutput(w io.Writer)
-
func (l *Logger) SetPrefix(prefix string)
列出Logger結構定義以及Logger結構操作的方法集
-
通過網頁查看文檔
-
godoc命令
$ godoc -http=:6060godoc會監聽6060端口，通過網頁訪問
http://127.0.0.1:6060，godoc基於GOROOT和GOPATH路徑下的代碼生成文檔的。打開首頁如下，我們自己項目工程文檔和通過go get的代碼文檔都在Packages中的Third party裏面。
編寫自己的文檔
-
1、設計接口函數代碼
創建documents/calc.go文件
-
/*
-
簡易計算器計算自定義包
-
*/
-
package documents
-
-
// 一種實現兩個整數相加的函數，
-
// 返回值爲兩整數相加之和
-
func Add(a, b int) int {
-
return a + b
-
}
-
-
// 一種實現兩個整數相減的函數，
-
// 返回值爲兩整數相減之差
-
func Sub(a, b int) int {
-
return a - b
-
}
-
-
// 一種實現兩個整數相乘的函數，
-
// 返回值爲兩整數相乘之積
-
func Mul(a, b int) int {
-
return a * b
-
}
-
-
// 一種實現兩個整數相除的函數，
-
// 返回值爲兩整數相除之商
-
func Div(a, b int) int {
-
if b == 0 {
-
panic("divide by zero")
-
}
-
-
return a / b
-
}
-
-
2、設計Example示例代碼
創建documents/calc_test.go文件，給calc.go中每個函數編寫Example函數
-
package documents
-
-
import (
-
"fmt"
-
)
-
-
func ExampleAdd() {
-
result := Add(4, 2)
-
fmt.Println("4 + 2 =", result)
-
-
// Output:
-
// 4 + 2 = 6
-
}
-
-
func ExampleSub() {
-
result := Sub(4, 2)
-
fmt.Println("4 - 2 =", result)
-
-
// Output:
-
// 4 - 2 = 2
-
}
-
-
func ExampleMul() {
-
result := Mul(4, 2)
-
fmt.Println("4 * 2 =", result)
-
-
// Output:
-
// 4 * 2 = 8
-
}
-
-
func ExampleDiv() {
-
result := Div(4,2)
-
fmt.Println("4 / 2 =", result)
-
-
// Output:
-
// 4 / 2 = 2
-
}
-
-
3、網頁查看文檔
注意以上兩個文件必須在$GOPATH/src路徑下，使用godoc命令創建文檔，用網頁打開顯示如下
編寫文檔規則
1、文檔中顯示的詳細主體內容，大多是由用戶註釋部分提供，註釋的方式有兩種，單行註釋"//"和代碼塊"/* */"註釋。
2、在源碼文件中，在package語句前做註釋，在文檔中看到的就是Overview部分， 注意：此註釋必須緊挨package語句前一行，要作爲Overview部分的，註釋塊中間不能有空行。
3、在函數、結構、變量等前做註釋的，在文檔中看到的就是該項詳細描述。註釋規則同上。
4、編寫的Example程序，函數名必須以Example爲前綴，可將測試的輸出結果放在在函數尾部，以"// Output:"另起一行，然後將輸出內容註釋，並追加在後面。