Godoc：为你的 Go 代码写文档

本文为官方 Go Blog 的中文翻译，详见 翻译说明

Andrew Gerrand
2011 年 3 月 31 日

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 文件中, 其中仅包含这些注释和 package 声明.

当编写任意长度的包注释时, 请记得注释的第一句话将出现在 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).

• URLs 都将转换为 HTML 链接; 而无需任何特殊标记.

注意以上规则都没有要求你做太多任何特别的事情.

实际上, godoc 的迷你方式的最大优点就是简单易用. 结果就是, 包括标准库在内的许多 Go 代码都已经遵循了该约定.

你自己的代码仅需如上所述的注释即可提供良好的文档. 安装在 $GOROOT/src/pkg 内的所有 Go 软件包以及任何 GOPATH 工作区已经可以通过 godoc 的命令行和 HTTP 接口访问, 并且你可以通过 -path 标志指定其他路径或仅通过在源目录中运行 "godoc .". 在源码目录里, 你可以参阅godoc 文档 来查看更多信息.

本译文仅用于学习和交流目的，转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议，如果我们的工作有侵犯到您的权益，请及时联系我们。

原文地址：https://learnku.com/docs/go-blog/godoc-d...

译文地址：https://learnku.com/docs/go-blog/godoc-d...