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 手册页，并且在工具为了简洁而截断它时（例如，提取第一行或句子时），使其读起来更好。
包声明上的注释应提供通用的包文档。这些注释可以很短，例如 sort 包的简要描述
// Package sort provides primitives for sorting slices and user-defined
// collections.
package sort
它们也可以像 gob 包的概述那样详细。对于需要大量介绍性文档的包，该包使用了另一个约定：包注释放在其自己的文件 doc.go 中，该文件仅包含这些注释和一个包子句。
无论编写多大的包注释，请记住它的 第一句话 将出现在 godoc 的 包列表 中。
不紧邻顶级声明的注释会被 godoc 的输出忽略，但有一个值得注意的例外。以单词 "BUG(who)” 开头的顶级注释被识别为已知 bug，并包含在包文档的“Bugs”部分中。“who”部分应是能够提供更多信息的人的用户名。例如，这是来自 bytes 包 的一个已知问题
// 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 文档。