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