godoc 介绍以及 Golang 注释规范

03 September 2018

IMG-THUMBNAIL

Golang 的文档从一开始发布就很完善了，但是很多用法我一直也么搞明白，今天详细研究了下，整理出来。

命令
代码中注释生成文档
doc.go
- 标题和段落：
- 代码
example_PackageName_test.go
最后

命令

golang 官方有有文档自动生成网站，地址是 godoc.org，比如：logger 的文档，godoc也可以在本地启动：

godoc -http=:6060

启动之后浏览器访问 localhost:6060，就能看到文档首页了。如果想看自己代码的文档，后面输入包的路径即可，比如：

http://localhost:6060/pkg/github.com/mnhkahn/gogogo/

代码或者注释文档的修改可以实时更新，不需要重启服务。

代码中注释生成文档

godoc支持package、const、var和func这些代码生成文档，而且只会对public变量(首字母大写)自动生成，而private变量则不会。

Package

在自动生成的时候，比如说对于包，对包介绍的内容用的就是包名上面的注释（变量和函数同理）。如果是多个包，就会把多个包的注释放在一起，按照文件名字母顺序排序。

如果多个注释中间有一个空行，那么只会算挨着变量位置的注释，其它的会被丢弃。

包生成的内容会放到文档的「Overview」里面。举个例子：

// package gogogo

/*
A web framework includes app server, logger, panicer, util and so on.
 */

变量和函数

和包类似，常量会放到「Constants」里，变量会放到「Variables」里，后面跟的是函数。

BUG

如果代码中有 bug，可以使用注释：

BUG(who): xxx

它会被识别为一个 bug，可以在文档中的「Bugs」中看到。

Deprecated

顺便提一句，弃用注释：

// Deprecated: xxx

这个注释不会体现在godoc中，但是还是挺有用的，Goland可以识别它并作出提示。

链接 URL 自动转成 HTML 的 a 标签

// SetFlag sets log flags. For more information, see the sdk https://golang.org/pkg/log/#pkg-constants.

注释自动生成

有一个自动生成注释的工具gocmt。安装和使用：

go get -u github.com/Gnouc/gocmt
gocmt -i $FilePath$

这个命令可以结合 Goland 的「External Tools」使用，检测文件是否改动，实时生成注释。

doc.go

如果包注释超过3行，可以把注释都迁移到doc.go文件中。

多行注释自然需要支持一些复杂的格式，而godoc支持的并不是Markdown这种熟悉的格式，下面详细说明一下。

标题和段落：

先看看效果：

如果首字母是大写，并且结尾没有标点符号，是标题。结尾有标点的自然是段落了。

代码

注释中的代码也可以转成代码块。如果是通过//来注释，因为默认注释和正文中间是一个空格，那么多整一个空格（最少多一个）就会被识别为代码了。而段注释也同理，比常规注释多一个空格就行，不过我喜欢用 tab。

example_PackageName_test.go

例子非常重要，基本上项目就是通过每个包的例子搭起来的。

例子文件需要创建一个新文件，格式是example_PackageName_test.go。不加 example 的前缀也可以，不过我觉得还是加上好一些，不加感觉和单元测试文件一样。包名也有要求，是PackageName_test。在这个文件中加函数，函数名的格式是ExampleFuncName。不加函数名的话是包级别示例。加函数名的话是函数级别的示例。

包级别的例子：

func Example() {
	logger.Info("hello, world.")
}

包级别的示例放在文档的开头处，而函数级别的示例放在函数后面，函数名得保持一致哦。

func ExampleNewLogger() {
    w := os.Stdout
    flag := log.Llongfile
    l := logger.NewWriterLogger(w, flag, 3)
    l.Info("hello, world")
}

最后

我们写代码都不太爱写注释，每当使用golint这些工具检测代码的时候，就会有一堆的错误提示。看了今天的文章，是不是愿意写注释了呢？

第二部分也是一个 Go 语言写注释的规范说明，大家可以参考这个。

本文涉及的代码可以从这里下载。赶紧 star 起来啊。

更多阅读：

原文链接：godoc 介绍以及 Golang 注释规范，转载请注明来源！

–EOF–

Golang 50