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包中方法

  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里面。
  

编写自己的文档

• 实例代码

  /*
  简易计算器计算自定义包
   */
  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
  }