golang go doc 与 godoc 文档生成查看

矫情吗；* 2021-07-28 21:18 320阅读 0赞

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]]

可用的标识：

<table> 
 <thead> 
  <tr> 
   <th>标识</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>-all</td> 
   <td>显示所有文档</td> 
  </tr> 
  <tr> 
   <td>-c</td> 
   <td>匹配程序实体时，大小写敏感</td> 
  </tr> 
  <tr> 
   <td>-cmd</td> 
   <td>将命令（main包）视为常规程序包，如果要显示main包的doc，请指定这个标识</td> 
  </tr> 
  <tr> 
   <td>-src</td> 
   <td>显示完整源代码</td> 
  </tr> 
  <tr> 
   <td>-u</td> 
   <td>显示未导出的程序实体</td> 
  </tr> 
 </tbody> 
</table>

示例

输出指定 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]]
    
    可以看到，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命令创建文档，用网页打开显示如下
    
    ![format_png][]

编写文档规则

1、文档中显示的详细主体内容，大多是由用户注释部分提供，注释的方式有两种，单行注释"//"和代码块"/\* \*/"注释。

2、在源码文件中，在`package`语句前做注释，在文档中看到的就是Overview部分， 注意：此注释必须紧挨`package`语句前一行，要作为Overview部分的，注释块中间不能有空行。

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

4、编写的`Example`程序，函数名必须以`Example`为前缀，可将测试的输出结果放在在函数尾部，以"// Output:"另起一行，然后将输出内容注释，并追加在后面。

[format_png]: /images/20210728/f98fbfd20525444882a8fa310b5d000a.png