Go语言学习21-程序文档

一、引言

在Go语言中，可以使用 godoc 命令在本机启动一个可被用于查看本机所有工作区中的所有代码包文档的 Web 服务。命令行中输入如下命令并执行：

godoc -http=:9090 –index

在浏览器中就可以像如下输入地址查看：

二、主要内容

2.1 编写程序注释

Go语言在注释风格中融入了 C 语言和 C++ 语言的特点。既可以使用 C++ 语言风格的行注释：

// 行注释

又可以使用 C 语言风格的块注释：

/*
  块注释
*/

注意： 无论是哪一种风格的注释都不能出现嵌套的情况。

2.2 代码包的注释

每个代码包都应包含一段独立的代码包注释。这段注释应该对当前代码包的功能和用途进行总体性的介绍。按照惯例，代码包注释应该被存放在当前代码包目录下的 doc.go 文件中。在这个 doc.go 文件中，应该有与包中其他源码文件相同的代码包声明语句，并在该声明语句之上以块注释的方式插入代码包注释。

当代码包中仅有一个源码文件的时候，建议源码文件的主文件名与当前代码包的名称相同。当然，如果在代码包中只有一个源码文件或代码包注释比较短，也可以将注释插入到当前代码包同名的源码文件中的代码包声明语句之上。

在标准库中，代码包 fmt 的代码包注释被放在了 $GOROOT/src/fmt/doc.go 中，与其相对应的文档页面如下：

在 Overview 中出现的就是 fmt 包的代码包注释行，也就是定义在 fmt/doc.go 中的。

2.3 程序实体的注释

在上图中的（带有链接的）Index 栏包含的是当前代码中的所有课导出的程序实体的文档的索引。点击后显示如下信息：

点击其中一个索引 type State 之后页面定位到与该索引相对应的程序实体文档的锚点处。例如：

点击有下划线的 State 处并点击，页面跳转到声明 fmt.State 的源代码处，如下：

程序实体的文档即是它的声明代码以及紧挨在上面的行注释，这里也体现了“代码即注释”的思想。

2.4 常量和变量的注释

Go语言语法允许一次声明一组常量或变量，程序实体声明编写注释如下示例：

// IP address lengths (bytes).
const (
    IPv4len = 4
    IPv6len = 16
)

上面代码位于代码包 net 中的源码文件 ip.go。对于这样一组声明来说，对它们的描述统一放在关键字 const（或关键字 var）之上且紧邻的注释行中，而不是分别为每一个常量（或变量）声明添加注释。

三、结语

本篇讲解了 Go 语言程序测试的 程序文档 的知识，后续博文我们开始实操一下 Go 语言，敬请期待！！！。

最后附上国内的 Go 语言社区

Go友团：该社区致力于为Go语言爱好者提供学习与交流的最佳环境。社区的组织者们都非常热爱Go语言，乐于分享，其技术精湛。其中包括了 Beego 的创始人。社区主页地址为: http://golanghome.com