golang go doc 与 godoc 文档生成查看

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

Go语言注释

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

///**/

packagepackagepackage

go docgodoc

go doc

go doc

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

go 1.12godocgo 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 help
usage: go doc [-u] [-c] [package|[package.]symbol[.method]]

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

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).

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)

通过网页查看文档

$ godoc -http=:6060

编写自己的文档

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

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
}

编写文档规则

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

packagepackage

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

ExampleExample