【转】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:"另起一行，然后将输出内容注释，并追加在后面。

标签：...,int,doc,golang,文档,godoc,func,go,Logger
来源： https://www.cnblogs.com/oxspirt/p/15522313.html