【翻译】Godoc：文档化 Go 代码

各位童鞋，愚人节好！由于鄙人愚钝，过不了这种高端节日，所以就不过节了。
所以今天即不会有鄙人要改名叫 mikeghost 的消息，也不会有诸如在 Android 上跑 iOS 应用的消息出现，当然，大家更不需要穿越的有木有来阅读本文。
生活还要继续……
原文《Godoc: documenting Go code》在此：http://blog.golang.org/2011/03/godoc-documenting-go-code.html
—————-翻译分割线—————-

Go 项目对待文档的态度是严肃的。文档是让软件易于处理和维护的重要的组成部分。当然，它必须编写良好并且准确，而且必须容易编写和维护。理想情况，它应当同代码在一起，这样文档就可以伴随代码一起更新。程序员建立良好文档越简单，对所有人好处越多。

最终，我们开发出了godoc文档工具。这个文章说明了用 godoc 生成文档的方法，以及解释了在你自己的项目中如何使用我们的约定和工具编写良好的文档。

Godoc 解析 Go 代码，包括注释，然后生成如 HTML 或纯文本的文档。这使得文档同它描述的代码紧密的结合。例如，通过 godoc 的 Web 界面你可以通过轻轻一击，从函数的文档跳转到其实现。

Godoc 的概念同 Python 的 Docstring 和 Java 的 Javadoc类似，但是设计上更为简单。godoc 读取的注释不应该是语言结构（例如 Docstring 那样）或者必须拥有某种机器识别的标记（例如 Javadoc 那样）。Godoc 注释就是良好注释，即便是在没有 godoc 的情况下，也是短小易读的。

约定是简单的：对类型、变量、常量、函数或者包的注释，在其定义前编写普通的注释即可，不要插入空行。Godoc 将会把这些注释识别为对其后的内容的文档。例如，这是 fmt 包Fprint 函数的文档（这部分不翻译了，原味一点）：

// Fprint formats using the default formats for its operands and writes to w.
// Spaces are added between operands when neither is a string.
// It returns the number of bytes written and any write error encountered.
func Fprint(w io.Writer, a ...interface{}) (n int, error os.Error) {

留意这些注释全部都是有它描述的元素名字的普通句子。这个重要的约定使我们可以生成各种不同格式的文档，从纯文本到 HTML，或者 UNIX 的 man 手册；或为了使其更容易阅读而进行截断，例如只显示第一行或者第一句的时候。

包上的注释会提供关于包大致信息的文档。这个注释可以很短，例如 sort 包的短短的描述：

// The sort package provides primitives for sorting arrays
// and user-defined collections.
package sort

也可以使用类似 gob package 那样的详细描述。这个包需要大量的介绍性文档，而使用了其他约定：包的注释在其doc.go文件里，包含了注释和包的使用条款。

不论编写任何大小的注释，都要记得，第一句话将出现在 godoc 的 package list中。

与顶级定义不相邻的注释，会被 godoc 的输出忽略，但有一个意外。以“BUG(who)”开头的顶级注释会被识别为已知的 bug，会被包含在包文档的“Bugs”部分。“who”应当是能提供更进一步信息的用户的名字。例如，这是来自于bytes 包的一个已知问题：

// BUG(r): The rule Title uses for word boundaries does not handle Unicode punctuation properly.

Godoc 作为可执行命令时有些不同。它不会检查指定的源码，而是在属于 Go 源码的特殊的包“documentation”中寻找。“package documentation”的注释作为命令文档。例如，查看godoc documentation和与其对应的doc.go文件。

用 Godoc 将注释转换为 HTML 时，有一些格式规则：

• 紧接着下一行的文本被认为是同一段的；你必须空出一行，来分隔段落。
• 预格式化文本必须在注释符号内缩进（阅读gob的doc.go作为例子）。
• 无序额外符号，URL 会被转换为 HTML 链接。

注意，这些规则没有哪个是需要你做超出通常要做的事情的范围的。

事实上，godoc 最棒的地方就是它的易用性。这样一来，许多 Go 代码，包括许多标准库，已经遵循这些约定。

可以用上面所描述的，将你自己的代码中的注释生成良好的文档。 任何安装在$GOROOT/src/pkg/的 Go 包，已经可以通过 godoc 的命令行和 HTTP 界面访问，你也可以通过 -path 标识添加指定的路径，或者在源代码目录执行“godoc .”。阅读godoc documentation了解更多细节。