go 注释与godoc

go 注释与godoc

1.1 注释

单行注释，以//打头。
多行注释有2种形式：
连续多行以//打头，注意多行注释之间不能出现空行。
在段前使用/，段尾使用/。
注释行前加缩进即可写go代码。
注释中给定的关键词。NOTE: 引人注意，TODO: 将来需要优化，Deprecated: 变量或函数强烈建议不要再使用

//Add 2个整数相加
//返回和。
//
//NOTE: 注释可以有多行，但中间不能出现空行（仅有//不算空行）。
func Add(a, b int) int {
	return a + b
}

/*
Sub 函数使用示例：
  for i:=0;i<3;i++{
	  Sub(i+1, i)
  }
看到了吗？只需要行前缩进，注释里就可以写go代码，是不是很简单。
*/
func Sub(a, b int) int {
	return a - b
}

//TODO: Prod 该函数不能并发调用，需要优化
func Prod(a, b int) int {
	return a * b
}

//Deprecated: Div 不要再调用了
func Div(a, b int) int {
	return a / b
}

1.1.1 代码中的注释

func main() {
	aaa()
	bbb()
	ccc()
}
//NOTE 表示这个函数么有返回值，鼠标放在main函数中被调用的时候，会显示这段注释，规范化
func aaa() {
	fmt.Printf("hello\n")
}
//TODO 表示这个函数需要优化,鼠标放在main函数中被调用的时候，会显示这段注释，规范化
func bbb() {
	fmt.Printf("hello\n")
}
//Deprecated 
//加了这个，被调用的部分会有横线，但是还能用,用于一些即将被弃用的函数
func ccc() {
	fmt.Printf("hello\n")
}

1.1.2 行注释与块注释

//是行注释

/*
是块注释
 */

1.1.3 注释的位置

针对行的注释在行上方或右侧。函数的上方在func xxx()上方。结构体的注释在type xxx struct上方。包注释在package xxx的上方。一个包只需要在一个地方写包注释，通常会专门写一个doc.go，里面只有一行package xxx和关于包的注释。

// FormatBool, FormatFloat, FormatInt, and FormatUint convert values to strings:
//
//	s := strconv.FormatBool(true)
//	s := strconv.FormatFloat(3.1415, 'E', -1, 64)
//	s := strconv.FormatInt(-42, 16)
//	s := strconv.FormatUint(42, 16)
package fmt

2.1 go doc

2.1.1 go doc是go自带的命令

上述命令查看entrance_class/util包的注释

go doc entrance_class/util

2.1.2 godoc

godoc是第三方工具，可以为项目代码导出网页版的注释文档。安装godoc命令如下

go get -u golang.org/x/tools/cmd/godoc
go install golang.org/x/tools/cmd/godoc@latest

启动http服务

godoc -http=:6060

用浏览器访问http://127.0.0.1:6060 ，可以查看go标准库的文档。