Go Doc文檔

Go為我們提供了快速生成文檔和查看文檔的工具，很容易編寫查看代碼文檔。在項目協作過程中，可以幫助我們快速理解代碼。


查看文檔方式有兩種：一種是通過終端查看，使用go doc命令，一種是通過網頁查看，使用godoc命令

通過終端查看文檔

• go doc命令

  $ go doc help
  usage: go doc [-u] [-c] [package|[package.]symbol[.method]]
  

  可以看到，go doc接受的參數，可以是包名，也可以是包里的結構、方法等，默認為顯示當前目錄下的文檔。
  
  

• 查看系統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=:6060
  

  godoc會監聽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:"另起一行，然后將輸出內容注釋，並追加在后面。