如何写高大上的 godoc（Go 文档）

最新推荐文章于 2024-05-17 04:18:11 发布

BigC哥

最新推荐文章于 2024-05-17 04:18:11 发布

阅读量1.4k

点赞数 1

分类专栏： go

本文链接：https://blog.csdn.net/weixin_43063753/article/details/104190053

版权

go 专栏收录该内容

10 篇文章 0 订阅

订阅专栏

godoc 命令和 golang 代码文档管理

https://www.jianshu.com/p/b9ce0cbaabd5

介绍

godoc 是 golang 自带的文档查看器，更多的提供部署服务
go doc 和 godoc 在 golang 1.13 被移除了，可以自行安装 golang.org go1.13 godoc

go get golang.org/x/tools/cmd/godoc
# 使用代理安装
GOPROXY=https://mirrors.aliyun.com/goproxy/ GO111MODULE=on go get golang.org/x/tools/cmd/godoc
godoc

godoc 基础使用

# 查看包内的文档，这里是查看 fmt 包中 Printf Println 的的文档
godoc fmt Printf Println
# 查看文档并包含源码
godoc -src fmt Printf
# 查看的同时显示示例代码
godoc -ex fmt Printf
# 显示文档的web版本 http -> 端口
godoc -http=:6060
# 显示 http 文档并开启本地索引
godoc -http=:6060 -index

要使用-index标记开启搜索索引，这个索引会在服务器启动时创建并维护。

否则无论在Web页面还是命令行终端中提交查询都会返回错误"Search index disabled: no results available"

如果不想提供如此多的结果条目，可以设置小一些的值

甚至，如果不想提供全文本搜索结果，可以将标记 -maxresults 的值设置为0，这样服务器就只会创建标识符索引，而根本不会创建全文本搜索索引
标识符索引即为对程序实体（变量、常量、函数、结构体和接口）名称的索引

go doc 这个是golang语言自带的文档查看工具

# 文档工具使用说明
go help doc
# 查看当前包的文档索引
go doc
# 查看目标包的文档索引
go doc [targetPackage]
# 查看目标包的某内容的文档索引
go doc [targetPackage].[函数名]
# 或者空格隔开也显示某内容的文档
go doc [targetPackage] [函数名]
# 子包的文档注释
go doc [targetPackage]/[subpackage]

golang发布查询代码注释文档

发布文档

godoc -http=:9090 -index

这样就在本机使用 http://127.0.0.1:9090/pkg/ 查看发布的包
当然你可以使用 http://127.0.0.1:9090/pkg/github.com/github.com/sinlov/XXXServer/userbiz/ 来查询自己代码包 github.com/sinlov/XXXServer/userbiz 下面的文档

查询发布文档

通过 godoc -q 命令查询发布文档服务，一般用于在另一个命令行终端甚至另一台能够与本机联通的计算机中通过如下命令进行查询

# 在本机用godoc命令启动了Go文档Web服务器，且IP地址为192.168.2.201、端口为9090
godoc -q -server="192.168.2.201:9090" Listener

标记 -q 开启了远程查询的功能
标记 -server="192.168.2.201:9090" 则指明了远程文档服务器的IP地址和端口号

如果不指明远程查询服务器的地址，那么该命令会自行将地址 :6060 和 golang.org 作为远程查询服务器的地址

这个地址 golang.org:6060 即是默认的本机文档Web站点地址和官方的文档Web站点地址

golang 代码文档管理

代码文档编写

其实只要按 go 的标准注释写法编写，就可以显示代码文档了

比如定义在 github.com/sinlov/XXXServer/userbiz 种有个文件 biz.go

// Biz implements a business
type Biz struct {
}

// business initialization
func (b *Biz) Init() {
}

注意 // 后面跟空格，才开始解析文档

如果需要展示代码需要 //后紧跟 [[:tab]] tab，那么 go doc 就会把这行当做代码来看
可惜的是，go没法自行在注释里面添加使用链接，而是解析器跟踪使用来生成链接

查看这个代码的文档命令就是 godoc github.com/sinlov/XXXServer/userbiz
查看某个函数的文档，比如 Init 函数就是 godoc github.com/sinlov/XXXServer/userbiz Init

代码文档导出

就使用上面文章中提到的 godoc -q -server= 指令，直接部署在服务器中就行

作者：木猫尾巴
链接：https://www.jianshu.com/p/b9ce0cbaabd5
来源：简书
著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。

编写自己的文档

1、设计接口函数代码

创建documents/calc.go文件

/*
简易计算器计算自定义包
 */
package documents

// 一种实现两个整数相加的函数，
// 返回值为两整数相加之和
func Add(a, b int) int {
    return a + b
}

// 一种实现两个整数相减的函数，
// 返回值为两整数相减之差
func Sub(a, b int) int {
    return a - b
}

// 一种实现两个整数相乘的函数，
// 返回值为两整数相乘之积
func Mul(a, b int) int {
    return a * b
}

// 一种实现两个整数相除的函数，
// 返回值为两整数相除之商
func Div(a, b int) int {
    if b == 0 {
        panic("divide by zero")
    }

    return a / b
}

2、设计Example示例代码

创建documents/calc_test.go文件，给calc.go中每个函数编写Example函数

package documents

import (
  "fmt"
)

func ExampleAdd() {
  result := Add(4, 2)
  fmt.Println("4 + 2 =", result)

  // Output:
  // 4 + 2 = 6
}

func ExampleSub() {
  result := Sub(4, 2)
  fmt.Println("4 - 2 =", result)

  // Output:
  // 4 - 2 = 2
}

func ExampleMul() {
  result := Mul(4, 2)
  fmt.Println("4 * 2 =", result)

  // Output:
  // 4 * 2 = 8
}

func ExampleDiv() {
  result := Div(4,2)
  fmt.Println("4 / 2 =", result)

  // Output:
  // 4 / 2 = 2
}

3、网页查看文档

注意以上两个文件必须在$GOPATH/src路径下，使用godoc命令创建文档，用网页打开显示如下

实际操作是放在E:\go1.13\src

为了灵活使用可以使用自定义的地址

godoc -http=localhost:6060 -goroot E:\go_path\go_st\documents

那么goroot 下面将需要doc 文件夹 src 文件夹 src 是主要存放项目包和代码的

实战：godoc -http=localhost:6060 -goroot E:\go_path\mqtt_agent

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-qqjQpl9U-1580914429305)(F:\MyBook\MypythonNote\go\go文档.assets\image-20200204112856128.png)]

编写文档规则

1、文档中显示的详细主体内容，大多是由用户注释部分提供，注释的方式有两种，单行注释"//“和代码块”/* */"注释。

2、在源码文件中，在package语句前做注释，在文档中看到的就是Overview部分，注意：此注释必须紧挨package语句前一行，要作为Overview部分的，注释块中间不能有空行。

3、在函数、结构、变量等前做注释的，在文档中看到的就是该项详细描述。注释规则同上。

4、编写的Example程序，函数名必须以Example为前缀，可将测试的输出结果放在在函数尾部，以"// Output:"另起一行，然后将输出内容注释，并追加在后面。

如何写高大上的 godoc（Go 文档）

amc

发表于后台全栈之路订阅

919

在这篇文章中：

[什么是 godoc](javascript:😉
[godoc 一览](javascript:😉
godoc 的 Overview
- [Overview 的文字部分](javascript:😉
- [Overview 的代码部分](javascript:😉
[godoc 的代码文档](javascript:😉
godoc 的代码示例
- [示例代码的声明](javascript:😉
[在官网上发布 godoc](javascript:😉

做 Go 开发时，我们在开源项目的主页上我们经常可以看到这样的一个徽章：

点击徽章，就可以打开 godoc.org 的网页，网页中给出了这个开源项目所对应的 Go 文档。作为 Go 语言的新手，我一度以为，godoc.org 上面的文档是需要开发者上传并审核的——要不然那些文档咋都显得那么专业呢。

然而当我写自己的轮子时，慢慢的我就发现并非如此。划重点：在 godoc.org 上的文档，都是 Go 自动从开源项目的工程代码中搜集、格式化后展现出来的。换句话说，每个人都可以写自己的 godoc 并且展示在 godoc.org 上，只需要遵从 godoc 的格式标准即可，也不需要任何审核动作。

本文章的目的是通过例子，简要说明 godoc 的格式，让读者也可以自己写一段高大上的 godoc。以下内容以我自己的 jsonvalue 仓库为例子。其对应的 godoc 在这里。读者可以点开，并与代码中的内容做参考对比。

本文地址：https://cloud.tencent.com/developer/article/1526609

什么是 godoc

顾名思义，godoc 就是 Go 语言的文档。在实际应用中，godoc 可能可以指以下含义：

https://godoc.org 中的内容
Go 开发工具安装之后，自带的一个命令，就叫做 godoc
Go 工具包的文档以及生成该文档所相关的格式

我们从 Go 自带的 godoc 工具讲起吧。前面我们说到的 godoc.org，是 Go 最为官方的文档网站。其中我们可以查阅 Go 原生 package 的文档说明。而 godoc 命令的作用，则是可以让我们在本地建立一个属于自己的 godoc 网站服务（官方的 godoc 其实也基本上是用同一个工具建立起来的）。

自建的 godoc 有两个作用，一是解决某局域网内无法访问 godoc.org 的尴尬，另一个则是可以本地调试自己的文档。

我们可以用下面的命令在本地启动自己的 godoc 服务：

godoc -http=127.0.0.1:6060 -play

或者简写为：

godoc -http=:6060 -play

在浏览器输入 http://127.0.0.1:6060 之后，就可以看到熟悉的 Go 文档页面了：

原理上，godoc 读取的包路径来自于 $GOROOT。因此，如果你要让本地的 godoc 认识并解析你自己的开发包，就应该在 $GOROOT 目录下按照路径结构放好自己的工程代码——软链接也是支持的。比如笔者的 jsonvalue 包，我放在了这个路径下：~/project/github.com/Andrew-M-C/go.jsonvalue，于是我就在 $GOROOT 下建了软链接：

$ go env | grep GOROOT | sed 's/GOROOT=//g' | xargs cd
$ ln -s ~/project/github.com ./

然后在浏览器中输入 http://127.0.0.1:6060/pkg/github.com/Andrew-M-C/go.jsonvalue/，就可以看到和 godoc.org 一样的页面了。

godoc 一览

Go 秉承 “注释即文档” 的理念，符合 godoc 的文档均从 Go 代码中提取并生成。我们还是从 jsonvalue 的 godoc 来看，一个一个说明。在 godoc 中，文档包含三大部分：

组成	作用
Overview 总览	包含包的 import 语句和概要说明
Index 目录	包含包中可见性为 public 的常量、类型、方法、函数的总目录及说明
Examples 示例	包含文档中所有示例的快速跳转
Files 文件	列出了包中所有代码文件的超链接

其中第四部分无关紧要。下面我们按顺序说明前三部分

godoc 的 Overview

Package jsonvalue 的 Overview 部分包含了三部分内容：

import 语句
文字说明
代码部分

其中 import 部分是 godoc 自动按照 URL 生成的，这个不用管。至于文字部分和代码部分，godoc 都是从源码中提取出来的。提取的原则是：

在代码中所有 package jsonvalue 语句中，找到其上方紧跟着的 // jsonvalue XXX 或者是 /* jsonvalue XXX */ 注释块
注释块可以有多行，但必须是连续的 // 或者 /* XXX */ 开头。如果需要换行，则留一行空注释
如果找到多个符合条件的注释，则按照文件字母序显示——建议把 Overview 放在一个注释块中，而不要分散撰写。

比如 jsonvalue 的 Overview 说明，统一放在 doc.go 中，这个文件中只有 package jsonvalue 语句以及包说明——这也是不少文章中推荐的做法。

Overview 的文字部分

请读者打开 doc.go，然后对比 godoc，就可以对照着看到文字部分是怎么被 godoc 呈现出来的。

Overview 的代码部分

在注释中，如果在 // 后面的注释文本中，如果以 tab 进行了锁进，那么 godoc 会将这一行视为代码块。比如下面这一段：

其中 “As a quick start:” 行的左边分别为：两个斜杠 + 一个空格。这一行，godoc 视为普通文字；而其余部分的左边为：两个斜杠 + 一个空格 + 一个tab，被 godoc 视为代码部分。于是我们在 godoc 网页上，就可以看到这样的显示结果了：

godoc 的代码文档

godoc 工具会搜寻代码中所有源码文件（自测文件除外），然后展示到页面上。搜索的依据如下：

搜寻对象是代码中所有的公共部分，包括常量、变量、接口、类型、函数
与 Overview 类似，紧跟着一个公共元素的、以该元素开头的注释段，会被 godoc 视为该元素的注释
换行逻辑和代码块逻辑的处理也与 Overview 相同

不过在源码说明中，更多的采用代码示例来说明逻辑，因此在这一环节中，代码块比较少用。

这里我用 jsonvalue 的 At() 函数为例。在代码中，对于 Set() 函数我是这么写的（请无视我蹩脚的英文）：

// At completes the following operation of Set(). It defines posttion of value in Set() and return the new value set.
//
// The usage of At() is perhaps the most important. This function will recursivly search for child value, and set the new value specified by Set() or SetXxx() series functions. Please unfold and read the following examples, they are important.
func (s *Set) At(firstParam interface{}, otherParams ...interface{}) (*V, error) {
    ......
}

godoc 解析并格式化效果如下：

godoc 的代码示例

读者可以注意到，在我的 At() 函数下，除了上文提到的文档正文之外，还有五个代码示例。那么，文档中的代码示例又应该如何写呢？

首先，我们应该新建至少一个文件，专门用来存放示例代码。比如我就把示例代码写在了 example_jsonvalue_test.go 文件中。这个文件的 package 名也不得与当前包名相同，而应该命名为 包名_test 的格式。

示例代码的声明

如何声明一个示例代码，这里我举两个例子。首先是在 At() 函数下名为 “Example (1)” 的示例。在代码中，我把这个函数命名为：

func ExampleSet_At_1() {
    ......
}

这个函数命名有几个部分：

函数名组成部分	说明
`Example`	这是示例代码的固有开头
`Set`	表示这是类型 `Set` 的示例
第一个下划线 `_`	分隔符，在这个分隔符后面的，是 `Set` 类型的成员函数名
`At`	表示这是函数 `At()` 的示例，搭配前面的内容，则表示这是类型 `Set` 的成员函数 `At()` 的示例
第二个下划线 `_`	分隔符，在这个分隔符后面的内容，是示例代码的额外说明
`1`	这是示例代码的额外说明，也就是前面 “Example (1)” 括号里的部分

另外，示例代码中应该包含标准输出内容，这样便于读者了解执行情况。标准输出内容在函数内的最后，采用 // Output: 单独起一行开头，剩下的每一行标准输出写一行注释。

相对应地，如果你想要给（不属于任何一个类型的）函数写示例的话，则去掉上文中关于 “类型” 的字段；如果你不需要示例的额外说明符，则去掉 “额外说明” 字段。比如说，我给类型 Opt 写的示例就只有一个，在代码中，只有一行：

func ExampleOpt() {
    ........
}

甚至连示例说明都没有。

如果一个元素包含多个例子，那么 godoc 会按照字母序对示例及其相应的说明排序。这也就是为什么我干脆在 At() 函数中，示例标为一二三四五的原因，因为这是我希望读者阅读示例的顺序。

在官网上发布 godoc

好了，当你写好了自己的 godoc 之后，总不是自己看自己自娱自乐吧，总归是要发布出来给大家看的。

其实发布也很简单：当你将包含了 godox 的代码 push 之后（比如发布到 github 上），就可以在浏览器中输入 https://godoc/org/${package路径名}。比如 jsonvalue 的 Github 路径（也等同于 import 路径）为 github.com/Andrew-M-C/go.jsonvalue，因此输入 godoc.org/github.com/Andrew-M-C/go.jsonvalue。

如果这是该页面第一次进入，那么 godoc.org 会首先获取、解析和更新代码仓库中的文档内容，并且格式化之后展示。在页面的底部，会列出该 godoc 的更新时间。

如果你发现官网上的 godoc 内容已经落后了，那么可以点 “Refresh now” 链接刷新它。

接下来更重要的是，把这份官网 godoc 的链接，附到你自己的 README 中。还是点上图的 “Tools” 链接，就可以在新页面中，看到相应的 godoc 徽标的链接了。有 html 和 markdown 格式任君选择。

本文章采用知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议进行许可。

原作者： amc，欢迎转载，但请注明出处。

原文标题：如何写高大上的 godoc（Go 文档）

发布日期：2019/10/24

原文链接：https://cloud.tencent.com/developer/article/1526609。

BigC哥

关注

1
点赞
踩
2

收藏

觉得还不错? 一键收藏
1
评论
如何写高大上的 godoc（Go 文档）

godoc 命令和 golang 代码文档管理https://www.jianshu.com/p/b9ce0cbaabd5介绍godoc 是 golang 自带的文档查看器，更多的提供部署服务go doc 和 godoc 在 golang 1.13 被移除了，可以自行安装 golang.org go1.13 godocgo get golang.org/x/tools/cmd/god...
复制链接

扫一扫