胡说八道

Go 是一个开源的编程语言，它能让构造简单、可靠且高效的软件变得容易。

现代计算机技术的发展已经快打破英特尔戈登·摩尔提出的摩尔定律了。计算机硬件的发展速度已经远远赶不上软件技术的发展，意味着在现有硬件基础上，高效的性能才是王道。像Go、Rust等这样的语言才是未来的主导语言。

在开发人员眼中，写出完美的API很容易，可写好文档却不容易，还有各种示例程序。然而Go、Rust等这类的语言本省就带了快捷编写文档的命令。用起来也相当舒服。接下来，通过实例来演示一下Go的API文档编写。

新建工程

|--src |----queue | | queue.go | | queue_test.go |------queueentry | | main.go 

queue.go

编写的重点在每个类型和方法上边的注释上，正是有了编写的这些注释，才有了文档中的说明，so， 一定要写好注释！

package queue // 先进先出队列 type Queue []int // 向队列中添加一个元素 // e.g. q.Push(9) func (q *Queue) Push (v int) { *q = append(*q, v) } // 从队列中删除第一个元素 func (q *Queue) Pop () int { head := (*q)[0] *q = (*q)[1:] return head } // 如果队列为空，则返回true func (q *Queue) IsEmpty () bool { return len(*q) == 0 }

queue_test.go

go还可以给写的库或者包写示例。我的IDE是GoLand, 你只要在与queue.go这个文件同目录构建一个queue_test.go文件，在文件中键入 func Ex..之后，编辑器会自动弹出提示，让你选择实现哪一个方法的示例的方法名。还是很贴心的。如果要写出示例程序执行的结果，只需要在示例程序中用// Output写出执行结果即可。

package queue import "fmt" func ExampleQueue_Pop() { q := Queue{1} q.Pop() // Output // 1 } func ExampleQueue_Push() { q := Queue{1} q.Push(2) } func ExampleQueue_IsEmpty() { q := Queue{1} if !q.IsEmpty() { fmt.Println("empty") } // Output // empty }

暂停......

最为一个库， 我们肯定要使用，所以，我们引用queue.go，将其打包为一个可执行文件，就当自个测试了。

main.go

相信你能看懂。

package queueentry import ( "fmt" "queue" ) func main() { q := queue.Queue{1} q.Push(2) fmt.Println(q[1]) }

在线看文档

go为我们提供了go doc 命令和 godoc两个命令查看文档，两个命令的使用方式也是不同的。如下是两个命令的大致使用。

go doc

$ go doc fmt.Println func Println(a ...interface{}) (n int, err error) Println formats using the default formats for its operands and writes to standard output. Spaces are always added between operands and a newline is appended. It returns the number of bytes written and any write error encountered.

godoc

$ pwd /gopath/to/src/queue/ $ godoc -http 127.0.0.1:8089 ... # 启动了一个web服务器，用浏览器即可打开。

在此，为了方便查看其它库的API，我们使用godoc命令格式。

执行后打开浏览器，会进入go提供的默认的网页。
点击顶部的Packages，该页面包含了Go的标准库，和你刚才写了注释的库。

在页面搜索queue,定位到该词的位置;

点击该文字，进入该库的说明文档；

至此，你的API的说明文档可以用了，可以把你的库交给你的小伙伴了。

打包

$ pwd /gopath/to/src/queue/entryqueue/ go build main.go # 生成entryqueue.exe

添加到bin

$ pwd /gopath/to/src/queue/entryqueue/ go install 

测试

$ entryqueue 2 # 测试成功

乱种取整

Go 为我们提供了一整套的编写文档的工具，不像java、JavaScript等语言都需要安全插件并且需要有特定的格式，操作很是麻烦。