【轉】golang go doc 與 godoc 文檔生成查看

注意，要將項目 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

國內的安裝方法

1.  
   mkdir -p $GOPATH/src/golang.org/x
2.  
   cd $GOPATH/src/golang.org/x
3.  
   git clone https://github.com/golang/tools.git
4.  
   cd tools/cmd/godoc
5.  
   go install
6.  
   ls -alh $GOPATH/bin

通過終端查看文檔

• go doc命令

  1.  
     $ go doc help
  2.  
     usage: go doc [-u] [-c] [package|[package.]symbol[.method]]
  可以看到，go doc接受的參數，可以是包名，也可以是包里的結構、方法等，默認為顯示當前目錄下的文檔。
   

• 查看系統log包信息

  1.  
     linux@ubuntu:/usr/ local/go/src/log$ go doc
  2.  
     package log // import "log"
  3.  
      
  4.  
     Package log implements a simple logging package. It defines a type, Logger,
  5.  
     with methods for formatting output. It also has a predefined 'standard'
  6.  
     Logger accessible through helper functions Print[f|ln], Fatal[f|ln], and
  7.  
     Panic[f|ln], which are easier to use than creating a Logger manually. That
  8.  
     logger writes to standard error and prints the date and time of each logged
  9.  
     message. Every log message is output on a separate line: if the message
  10.  
      being printed does not end in a newline, the logger will add one. The Fatal
  11.  
      functions call os.Exit(1) after writing the log message. The Panic functions
  12.  
      call panic after writing the log message.
  13.  
       
  14.  
      const Ldate = 1 << iota ...
  15.  
      func Fatal(v ...interface{})
  16.  
      func Fatalf(format string, v ...interface{})
  17.  
      func Fatalln(v ...interface{})
  18.  
      func Flags() int
  19.  
      func Output(calldepth int, s string) error
  20.  
      func Panic(v ...interface{})
  21.  
      func Panicf(format string, v ...interface{})
  22.  
      func Panicln(v ...interface{})
  23.  
      func Prefix() string
  24.  
      func Print(v ...interface{})
  25.  
      func Printf(format string, v ...interface{})
  26.  
      func Println(v ...interface{})
  27.  
      func SetFlags(flag int)
  28.  
      func SetOutput(w io.Writer)
  29.  
      func SetPrefix(prefix string)
  30.  
      type Logger struct{ ... }
  31.  
      func New(out io.Writer, prefix string, flag int) *Logger
  列出當前包中方法、結構、常量等
   

• 查看系統log包中Fatal方法

  1.  
     linux@ubuntu:/usr/ local/go/src/log$ go doc log.Fatal
  2.  
     func Fatal(v ...interface{})
  3.  
     Fatal is equivalent to Print() followed by a call to os.Exit(1).
  列出當前函數和注釋說明
   

• 查看系統log包中Logger結構

  1.  
     linux@ubuntu:/usr/ local/go/src/log$ go doc Logger
  2.  
     type Logger struct {
  3.  
     // Has unexported fields.
  4.  
     }
  5.  
     A Logger represents an active logging object that generates lines of output
  6.  
     to an io.Writer. Each logging operation makes a single call to the Writer 's
  7.  
     Write method. A Logger can be used simultaneously from multiple goroutines;
  8.  
     it guarantees to serialize access to the Writer.
  9.  
      
  10.  
       
  11.  
      func New(out io.Writer, prefix string, flag int) *Logger
  12.  
      func (l *Logger) Fatal(v ...interface{})
  13.  
      func (l *Logger) Fatalf(format string, v ...interface{})
  14.  
      func (l *Logger) Fatalln(v ...interface{})
  15.  
      func (l *Logger) Flags() int
  16.  
      func (l *Logger) Output(calldepth int, s string) error
  17.  
      func (l *Logger) Panic(v ...interface{})
  18.  
      func (l *Logger) Panicf(format string, v ...interface{})
  19.  
      func (l *Logger) Panicln(v ...interface{})
  20.  
      func (l *Logger) Prefix() string
  21.  
      func (l *Logger) Print(v ...interface{})
  22.  
      func (l *Logger) Printf(format string, v ...interface{})
  23.  
      func (l *Logger) Println(v ...interface{})
  24.  
      func (l *Logger) SetFlags(flag int)
  25.  
      func (l *Logger) SetOutput(w io.Writer)
  26.  
      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文件

  1.  
     /*
  2.  
     簡易計算器計算自定義包
  3.  
     */
  4.  
     package documents
  5.  
      
  6.  
     // 一種實現兩個整數相加的函數，
  7.  
     // 返回值為兩整數相加之和
  8.  
     func Add(a, b int) int {
  9.  
     return a + b
  10.  
      }
  11.  
       
  12.  
      // 一種實現兩個整數相減的函數，
  13.  
      // 返回值為兩整數相減之差
  14.  
      func Sub(a, b int) int {
  15.  
      return a - b
  16.  
      }
  17.  
       
  18.  
      // 一種實現兩個整數相乘的函數，
  19.  
      // 返回值為兩整數相乘之積
  20.  
      func Mul(a, b int) int {
  21.  
      return a * b
  22.  
      }
  23.  
       
  24.  
      // 一種實現兩個整數相除的函數，
  25.  
      // 返回值為兩整數相除之商
  26.  
      func Div(a, b int) int {
  27.  
      if b == 0 {
  28.  
      panic("divide by zero")
  29.  
      }
  30.  
       
  31.  
      return a / b
  32.  
      }

• 2、設計Example示例代碼

  創建documents/calc_test.go文件，給calc.go中每個函數編寫Example函數

  1.  
     package documents
  2.  
      
  3.  
     import (
  4.  
     "fmt"
  5.  
     )
  6.  
      
  7.  
     func ExampleAdd() {
  8.  
     result := Add( 4, 2)
  9.  
     fmt.Println( "4 + 2 =", result)
  10.  
       
  11.  
      // Output:
  12.  
      // 4 + 2 = 6
  13.  
      }
  14.  
       
  15.  
      func ExampleSub() {
  16.  
      result := Sub( 4, 2)
  17.  
      fmt.Println( "4 - 2 =", result)
  18.  
       
  19.  
      // Output:
  20.  
      // 4 - 2 = 2
  21.  
      }
  22.  
       
  23.  
      func ExampleMul() {
  24.  
      result := Mul( 4, 2)
  25.  
      fmt.Println( "4 * 2 =", result)
  26.  
       
  27.  
      // Output:
  28.  
      // 4 * 2 = 8
  29.  
      }
  30.  
       
  31.  
      func ExampleDiv() {
  32.  
      result := Div( 4,2)
  33.  
      fmt.Println( "4 / 2 =", result)
  34.  
       
  35.  
      // Output:
  36.  
      // 4 / 2 = 2
  37.  
      }

• 3、網頁查看文檔

  注意以上兩個文件必須在$GOPATH/src路徑下，使用godoc命令創建文檔，用網頁打開顯示如下

  
   

編寫文檔規則

1、文檔中顯示的詳細主體內容，大多是由用戶注釋部分提供，注釋的方式有兩種，單行注釋"//"和代碼塊"/* */"注釋。

2、在源碼文件中，在package語句前做注釋，在文檔中看到的就是Overview部分， 注意：此注釋必須緊挨package語句前一行，要作為Overview部分的，注釋塊中間不能有空行。

3、在函數、結構、變量等前做注釋的，在文檔中看到的就是該項詳細描述。注釋規則同上。

4、編寫的Example程序，函數名必須以Example為前綴，可將測試的輸出結果放在在函數尾部，以"// Output:"另起一行，然后將輸出內容注釋，並追加在后面。