golang-使用godoc 工具编写代码注释

导语：良好的注释是代码可维护的基础之一，作为golang 开发者，更应该意识到go 官方已经提供了godoc 工具，只要我们代码的注释是按照规范来，最后也能生成比较直观的“文档”，因此平时开发 的时候也应该重视注释的细节。

一、本地安装godoc 工具

go get golang.org/x/tools/cmd/godoc

然后本地启动：
godoc -http=:6060

然后就可以查看go 原生库的文档了，只要代码本身的注释是比较规范的，生成的godoc 也会比较好看.

二、查看本地项目的godoc

如果本地的项目没有在GOROOT 路径下，除非设置软链接，才能通过godoc 来看否则只能通过 go doc 指令查看：

cd 到项目根目录，然后直接执行 go doc 即可。

go doc util

效果如下：

三、简述godoc 规范

官方示例：sync godoc

1、package 注释

首先，整个package ，但是不需要每个方法都写上一样的定义，只要在其中一个文件中写上就可以了。

2、结构体注释

如上图，直接在 struct 前面定义即可。

注意：struct 的对象如果没有加上注释，在godoc 中就会显示：contains filtered or unexported fields

3、方法注释

注释位置同上
一般对外的方法是一定要添加注释的

4、常量注释

如果要让const 显示出注释，就应该所有的常量都添加注释
如果只添加了部分常量，有可能显示会有问题

5、doc.go

一般用在项目的根目录中。

前面说到添加 package 的注释，可以在package 下的任意一个文件中添加，但是如果本身根目录的文件就很多了，有的时候确实很难定到底应该放到哪个文件中，而且后期不好找。
doc.go 一般就是作为 package 的注释用的，也经常出现在开源项目的根目录中。

举个例子：grpc

四、实战：给自己的项目添加godoc

项目地址
生成的godoc 地址（util包）

开源项目的godoc 直接通过 godoc.org/项目完整路径 访问即可。