03 September 2018

IMG-THUMBNAIL

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

命令

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

godoc -http=:6060

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

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

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

代码中注释生成文档

godoc支持packageconstvarfunc这些代码生成文档,而且只会对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 程序员,可以给我发简历:lichao@cyeam.com。

本站总访问量次; 本站访客数人次; 本文总阅读量次;



相关推荐

blog comments powered by Disqus。如果你看不到评论框,加我微信或者自己想办法。