本文翻译自《Godoc: documenting Go code》。
Andrew Gerrand
2011/03/31
[注，2022年6月：有关Go代码文档的更新指南，请参阅“Go文档注释”]
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, err error) {请注意，这个注释是一个完整的句子，以它所描述的Go语言语法元素的名称开头。这一重要的约定使我们能够生成各种格式的文档，从纯文本到HTML再到UNIX手册页，并且当工具为了简洁而截断文档时，例如当它们提取第一行或第一个句子时，可以更好地阅读文档。
在package的声明之上的注释会生成这个包的文档。这些注释可以很短，就像sort包的简短描述一样：
// Package sort provides primitives for sorting slices and user-defined
// collections.
package sort注释也可以像gob包的概述一样详细。对于需要大量介绍性文档的包，该包使用了另一种约定：包注释放在自己的doc.go文件中，该文件只包含这些注释和一个package gob包声明语句。
在编写任何大小的包注释时，请记住它的第一句话将出现在godoc的包列表中。
与顶层声明语句不相邻的注释在godoc的输出中会被省略，除了一个明显的例外：以短语“BUG(who)”开头的顶层注释被识别为已知Bug，并在godoc的输出中包含在包文档的“Bugs”小节。“who”应该是可以提供更多信息的人的用户名。例如，这是字节包中的一个已知Bug：
// BUG(r): The rule Title uses for word boundaries does not handle Unicode punctuation properly.有时，一个结构体的字段、一个函数、一个类型，甚至整个包都会变得多余或不再需要，但必须保留以与现有程序兼容。要发出不应使用某个标识符的信号，请在其文档注释中添加一段以“Deprecated:”开头的段落，后跟一些有关弃用的信息。
Godoc在将注释文本转换为HTML时使用了一些格式规则：
- 随后的几行文本被视为同一段落的一部分；你必须使用一个空白行来分隔段落。
- 预格式化的文本必须相对于周围的注释文本进行缩进（有关示例，请参阅gob的doc.go）。
- URL将被转换为HTML链接；不需要特殊标记。
请注意，这些规则都不要求你做任何不同寻常的事情。
事实上，godoc最棒的地方在于它的易用性。因此，许多Go代码，包括所有的标准库，都已经遵循了这些约定。
你自己的代码只要有如上所述的注释就可以提供良好的文档。安装在$GOROOT/src/pkg中的任何Go软件包和任何GOPATH工作空间都可以通过godoc的命令行和HTTP接口进行访问，你可以通过-path标志或在源代码目录中运行“godoc.”来指定其他索引路径。有关更多详细信息，请参阅godoc文档。