【转】golang go doc 与 godoc 文档生成查看

注意，要将项目 zz (文件夹）放在GOPATH指定的某个目录的src下。如GOPATH为：GOPATH="/root/go:/data/code"

则可以将目录 zz 放到  /data/code/src下面！！

b.go

　　b_test.go

----------------------------

Go语言项目十分重视代码的文档，在软件设计中，文档对于软件的可维护和易使用具有重大的影响。因此，文档必须是书写良好并准确的，与此同时它还需要易于书写和维护。

Go语言注释

Go语言中注释一般分为两种，分别是单行注释和多行注释

///**/

packagepackagepackage

go docgodoc

go doc

go doc

Go语言程序实体是指变量、常量、函数、结构体以及接口。

程序实体标识符就是程序实体的名称。

go doc 用法

go doc [-u] [-c] [package|[package.]symbol[.methodOrField]]

可用的标识：

示例

输出指定 package ，指定类型，指定方法的注释

$ go doc sync.WaitGroup.Add

输出指定 package ，指定类型的所有程序实体，包括未导出的

$ go doc -u -all sync.WaitGroup

输出指定 package 的所有程序实体（非所有详细注释）

$ go doc -u sync

godoc

godoc

go 1.12godocgo 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 -http=:6060

编写自己的文档

• 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、文档中显示的详细主体内容，大多是由用户注释部分提供，注释的方式有两种，单行注释"//"和代码块"/* */"注释。

packagepackage

3、在函数、结构、变量等前做注释的，在文档中看到的就是该项详细描述。注释规则同上。

ExampleExample