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