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

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

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

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

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

Godoc是什么?

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

• 记录类型、变量、常量、函数和包的方法是在其声明前直接写入常规注释，中间不包含空行。
• Godoc将把该评论作为文本显示在它所记录的项目旁边

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

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

在GoCenter GoDoc

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

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

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

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

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

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

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

为Godoc准备围棋模块

正如你所看到的，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示例()-包作为一个整体的示例
• func ExampleFunction() -包的函数示例
• func ExampleType()—包类型示例
• func ExampleType_Method() -一个包类型的方法示例

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

做一个日期

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

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

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

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