定义和使用Go语言注释（godoc工具提取注释内容）

Go语言中的注释主要分为两类：单行注释和多行注释。

• 单行注释，称为行注释，是最常见的注释形式，以//开头的单行注释可以在任何地方使用。
• 多行注释称为块注释，以/*开头，以*/结尾，并且不能嵌套。多行注释通常用于包文档描述或注释成块的代码片段。

单行注释的格式为：

//单行注释

多行注释的格式为：

/*
第一行注释
第二行注释
…
*/

每个包都有一个关联的注释，在使用 package 语句声明包名称之前，您应该添加相应的注释来简要描述包的特性和功能。

同时，包声明之前的注释内容默认被视为包的文档。一个包可以分布在多个文件中，但只需要对其中一个进行注释。

您可以用空行分隔多个注释，如下所示：

 // パッケージsupermanは、世界を救うためのメソッドを実装します。
//
// 経験から、世界を救う際に役立つ手順はわずかな数しかないことが示されています。
package superman 

我们建议添加与代码中的变量、常量、函数和其他对象相对应的注释。这将有助于您以后维护代码，例如注释下面代码中的 EnterOrbit 函数。

 // enterOrbitは、スーパーマンを地球周回軌道に飛行させ、多数の星の救済の可能性を提供します。
func enterOrbit() error {
   ...
} 

如果开发人员想要了解某个包，他们可以使用 godoc 查看该包的文档。让我向您展示如何使用 godoc 工具。

戈多克工具

godoc工具从Go程序和包文件中提取顶级声明的第一行注释以及每个对象的相关注释，并生成相关文档。它还可以用作网络服务器，您可以在其中在线查看文档。官网（ https://golang.dev/ ）就是采用这种形式实现的。

不过在Go语言1.13版本中，godoc工具已经被移除，可以通过go get命令获取。

go get golang.org/x/tools/cmd/godoc

由于防火墙的原因，国内用户可能无法通过go get命令获取godoc工具，需要手动获取。

• 首先，从 GitHub ( https://github.com/golang/tools.git ) 下载 golang.org/x/tools 包。
• 接下来，将下载的文件解压到 GOPATH 下的 src\golang.org\x\tools 目录。如果没有，您可以手动创建它。
• 打开GOPATH下的src\golang.org\x\tools\cmd\godoc目录，打开该目录下的命令行工具，运行go build命令生成godoc.exe可执行文件。
• 最后将生成的godoc.exe文件移动到GOPATH下的bin目录下。 （需要将GOPATH下的bin目录添加到环境变量Path中）

完成上述步骤后，您将能够使用 godoc 工具，它有几个常见用途：

• go doc package：获取包的文档注释。例如， go doc fmt显示 godoc 生成的 fmt 包的文档注释。
• go doc package/subpackage：获取子包的文档注释，例如go doc container/list 。
• go doc package function：获取包中函数的文档注释。例如， go doc fmt Printf展示了如何使用 fmt.Printf()。

下图显示了如何使用go doc命令检索包的文档注释。

godoc工具还可以检索位于Go安装目录中../go/src的评论内容，并将这些评论内容集成到您的Web服务器中进行预览。在命令行中输入godoc -http=:6060并使用浏览器打开 http://localhost:6060 以查看本地文档浏览服务器提供的页面。