Godoc在GoCenter讲述一个Go模块的故事

更新:截至2021年5月1日，GoCenter中央存储库已经日落，所有功能将被弃用。有关中心日落的更多信息，请阅读弃用博客文章

使用来自其他开发者社区的开源Go模块就像去相亲一样。这个“了解你”的阶段可能会很尴尬和冒险。你提前知道的越多，你就会过得越好，对吧?

在使用软件时，拥有准确和精确的文档是最重要的方面之一。好的软件文档讲述了一段特定的代码是做什么的，以及如何使用它。它的主要功能是使软件易于访问和维护

Golang项目非常重视文档，并为开发人员提供了一种方法使用Godoc快速轻松地记录他们的软件帮助作者和消费者去模块，我们已经在JFrog GoCenter中加入了Godoc生成。

戈多克是什么?

Godoc是Golang项目工具，已经为开发人员提供了近十年的时间。它解析包括注释在内的Golang源代码，并生成HTML或纯文本形式的文档。Godoc依赖于一些Go注释约定，这些约定通常被训练有素的开发人员所遵循。例如:

• 类型、变量、常量、函数和包都是通过在声明之前编写常规注释来记录的，中间没有空行。
• Godoc将把该评论作为文本呈现在它所记录的项目旁边

下面的例子描述了一个简单的日期函数。我们可以看到，函数的描述在代码中被格式化:

当源代码被Godoc工具处理时，它会以高度可读的格式生成该函数的文档:

GoCenter中的GoDoc

JFrog GoCenter是一个社区GOPROXY公开可用的Go模块。通过这个免费的不可变模块版本库，Go开发人员可以确定他们在应用程序中使用的Go模块中的内容。

但GoCenter同样重要的部分是通过其丰富的UI提供的关于每个Go模块的信息。当查看去模块条目，附加数据的选项卡包括:

• 模块的依赖项列表
• 哪些其他Go模块使用它
• 重要的使用指标，如分支、贡献者和拉取请求的数量
• 已知的安全漏洞由JFrog x射线检测

现在我们在GoCenter中添加了一个新的标签，用来显示每个模块版本的Godoc HTML输出:

GoCenter通过在每个模块版本的源文件上自动运行Godoc来生成这个选项卡的信息。Godoc信息也可用于伪版本，因为许多Go模块使用伪版本作为依赖项。

当一个模块有子目录时，它们会列在Godoc末尾的一个表中。

点击子目录名，将显示该子目录下包的Godoc:

为Godoc准备Go模块

正如你所看到的，GoCenter中的Godoc为Go模块的消费者提供了更多的信息，帮助他们使用可用的包。

当鼓励其他开发人员使用文档丰富的模块时，Go模块作者也会受益。这意味着Golang开发人员应该培养通过Godocs生成有用文档的技能和纪律。

通过安装Godoc工具并运行godoc-http: 6060您将能够测试和检查本地安装的每个包的文档。默认情况下，Godoc使用GOROOT美元和“美元GOPATH(如果设置了)来查看它找到的包。的godoc命令将自动在模块模式下运行，如果包中有go.mod文件。

有关使用Godoc的完整信息，请参阅Godoc文档．

Godoc技巧

当使用Godoc时，记住下面的事情是很有用的，因为它们会使在Go中创建文档变得更简单:

• 对包声明的注释通常应该提供一般的包文档
  • 这些通常是1或2句话的长度
  • 对于更大、更详细的描述，文档应该包含自己的文档。去文件
• 不与顶级声明相邻的注释将从文档中省略
• 使用这个词错误(世卫组织)在顶级注释的开头，注释将被识别并归类为已知错误，并将包含在错误包文档的部分

Godoc还以示例的形式提供了可执行文档。以下是示例函数的特点:

• 他们把没有论点
• 它们驻留在包中_test.go归档，从word开始例子
• 它们可能包括以……开头的结束语注释输出:并在运行测试时与函数的标准输出进行比较。
• 它们作为包测试套件的一部分被编译和执行。
  • 如果没有输出:定义的示例将被编译但不执行

以下是示例函数的命名约定:

• func Example() -包作为一个整体的例子
• func ExampleFunction() - package的函数示例
• func ExampleType() -一个包类型的示例
• func ExampleType_Method() -一个包类型的方法示例

这里有一个例子日期包装功能时间它住在examples_test.go在包级别。

约会

通过提供函数及其用法的可读摘要，Godoc可以帮助您理解如何使用新的Golang代码。由于Godoc是Golang项目的一部分，因此许多Go模块作者都会相应地格式化他们的注释。

如果你是一个Go模块作者，为Godocs组织你的注释是一个帮助和鼓励其他开发者使用你所创建的东西的好方法。

使Godoc信息更容易获得是JFrog GoCenter的最新功能，它可以帮助您在使用Go模块之前尽可能多地了解它。

在进行配对之前，您需要了解潜在的Go模块合作伙伴的故事(文档)、他们的家庭(依赖项)、他们的朋友(被使用)以及任何危险信号(安全漏洞)。看看GoCenter吧，你会看到它是如何帮助你找到最好的伴侣的。