Godoc - golang 注释与文档工具

Godoc - golang 注释与文档工具

基本规则

The Go project takes documentation seriously! 所以godoc横空出世了

规则很简单，用其中的一句话就可以说明：

to document a type, variable, constant, function, or even a package, write a regular comment directly preceding its declaration, with no intervening blank line.

只要用一个常见的注释，直接加在声明前，并没有插入的空行，这样就可以自动文档化包，类型，接口，变量，常量…

我举两个错误例子说明一下

以下是没有紧跟声明的错误例子

// Add 两数相加

func Add(n1,n2 int)int{
    return n1+n2
}

以下是将注释切开了的错误例子

// Add

// 两数相加
func Add(n1,n2 int)int{
    return n1+n2
}

正确的应该是以下：

// Add 两数相加（这一行会被截取为简短介绍）
// 两数相加的注意事项以及原理（这一行作为超级详细的介绍）
func Add(n1,n2 int)int{
    return n1+n2
}

同时需注意，注释需以 它描述的东西的名字 开发（比如上例中，是描述一个func，就已这个func的name开头 – Add），可以方便godoc在转html或者unix man page的时候，截取它的简短介绍<