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

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

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

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

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

什么是Godoc?

Godoc是Golang的一个项目工具，开发人员已经使用了近十年。它解析包括注释在内的Golang源代码，并以HTML或纯文本的形式生成文档。Godoc依赖于一些严格的开发人员通常遵循的Go注释约定。例如:

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

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

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

GoCenter中的GoDoc

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

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

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

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

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

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

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

为Godoc准备Go模块

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

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

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

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

Godoc技巧

在使用Godoc时，记住以下几点很有用，因为它们会让在Go中创建文档变得更简单:

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

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

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

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

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

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

约会

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

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

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

在任何配对之前，你想知道你潜在的Go模块合作伙伴的故事(文档)，他们的家庭(依赖关系)，他们的朋友(被使用)，以及任何危险信号(安全漏洞)。看看GoCenter吧，你会看到它如何帮助你找到最好的伴侣。