golang注释和文档说明及go doc和godoc

golang注释

• 单行注释

是最常见和使用的注释方式，以 // 开头，其后面的内容都是注释。

可以是单独的一行，也可以是在某个语句的后面。

比如：

package main

// 导入我们需要包，而且只导入需要的，多余导入会引起编译错误
import (
    "fmt"  // 这里也是单行注释，跟在某个语句的后面
)

• 多行注释

不常使用，一般用来做代码块的注释 或者是 包的文档型描述， 文档型描述需要尽可能详细说明包及其对外暴露的函数等，有时候单行注释使用不方便

比如：

package convert

import (
	"strconv"
)

/*
 * 这里是多行注释，进行自定义包中对外函数的详细描述
 * 描述可以尽可能详细，让大家能读懂其作用是什么
 */

func Convert(name string) (string) {
    ... ...
}

golang 文档描述

在进行项目开发的时候，代码的注释是必不可少的，但是对于go来说，自定义包及其包中对外暴露的函数，添加额外的特殊说明，方便使用者快速了解使用。

这种特殊的说明就是文档描述，书写有要求规范

• 包描述

  一般是在紧挨着 package 关键字上面一行，描述以 Package 开头，比如

  // Package convert is ...
  package convert

• 函数描述

  函数描述是在func SomeName() 的紧挨着上面一行， 一般建议以 Function 开头，比如

  // Function SomeName is uesd to ...
  func SomeName() {
      ... ...
  }

go doc 工具

go doc 命令是基于go命令的。主要的作用是打印出go程序的文档信息，就是我们上面的所讲的文档描述。

通过 go help sub-command 可以查看具体命令的用法，比如这里的go help doc

在实际使用中，不清楚第三方如何使用的时候，go doc 就非常有用，比如字符串转浮点型，

• go doc strconv

  直接后面跟 包 名称，可以查看包中都有哪些对外暴露的方法、变量等

• go doc strconv ParseFloat

  后面跟 包名 加 对应的方法名、变量名等，可以查看具体的说明和用法

  # go doc strconv ParseFloat
  package strconv // import "strconv"
  
  func ParseFloat(s string, bitSize int) (float64, error)
      ParseFloat converts the string s to a floating-point number with the
      precision specified by bitSize: 32 for float32, or 64 for float64. When
      bitSize=32, the result still has type float64, but it will be convertible to
      ... ...

  再比如(注意使用 package.method 或者 package method 都可以)

  # go doc fmt.Sprintf
  package fmt // import "fmt"
  
  func Sprintf(format string, a ...interface{}) string
      Sprintf formats according to a format specifier and returns the resulting
      string.

• go doc 后面不添加任何参数

  会打印当前目录所代表的代码包的文档及当中的包级别程序实体的列表

go doc 参数说明

• -c 区分参数中字母的大小写
• -u 同时会打印出 不可导出 的程序实体，默认只打印 可导出 实体 （golang的能否被其他包调用的原则就是可导出 ，首字母大写）
• -cmd 同时打印出main包中的可导出的程序实体
• -short 没有实体文档用一行标识

godoc 和 go doc 傻傻分不清楚

godoc 和 go doc 很像，但是不一样哦~

• go doc是go的子命令，用于在命令行输出相关实体的文档说明

• godoc 是通过在本地启动一个web程序，通过浏览器来展示本地相关包的文档信息，类似golang的在线文档

• godoc默认是没有安装的，可以通过如下命令进行安装，默认是安装到GOBIN 环境变量定义的目录中

go get -v -u golang.org/x/tools/cmd/godoc

启动本地web访问在线文档的方式

godoc -http=:8080

然后在浏览器输入 http://localhost:8080 即可查看