Golang学习:生成文档和示例代码

类似与javadoc，go也可以自动生成doc文档。我们主要使用到的是godoc命令

配置

godoc命令主要用于在无法联网的环境下，以web形式，查看Go语言标准库和项目依赖库的文档。go 1.13版本后移除了godoc相关的一些命令,因此需要手动安装

• 第一步配置相关代理
• 第二步命令行输入,安装godoc

# 第一步配置
go env -w GO111MODULE=on
go env -w GOPROXY="https://goproxy.io,direct"
# 第二步配置
go get golang.org/x/tools/cmd/godoc

代码示例

在这个目录下，我们创建一个docTest包，代码如下：

主文件代码

注意：要将项目docTest放在GOPATH指定的目录的src下。如GOPATH为: GOPATH="/Users/ljs/GoProject"

则可以将项目docTest放在/Users/ljs/GoProject/src下面。

示例代码

编写文档规则

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

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

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

4、编写的Example程序，文件名以_test.go为后缀，函数名必须以Example为前缀，可将测试的输出结果放在在函数尾部，以"// Output:"另起一行，然后将输出内容注释，并追加在后面。go语言的示例代码,不仅可以执行;而且还会检查一下你的期望值是否跟结果一样;如果不一样会有反馈;示例代码也可以作为测试,但是不仅仅是测试;还可以作为用户的example

查看doc文档

godoc会监听6060端口，通过网页访问 http://127.0.0.1:6060/pkg/docTest/，和GOPATH路径下的代码生成文档的。打开首页如下，我们自己项目工程文档和通过go get的代码文档都在Packages中的Third party里面。