go doc命令

go doc 命令主要作用时打印出go程序的注释文档。实际使用中可以使用go doc命令方便的查看文档信息。如：使用go doc fmt命令查看fmt包的文档信息。实际使用中可以避免频繁的打开网页文档或者查看源码注释。

> go doc fmt
package fmt // import "fmt"
​
Package fmt implements formatted I/O with functions analogous to C's printf
and scanf. The format 'verbs' are derived from C's but are simpler.        
​
​
Printing
​
The verbs:
​
General:
​
    %v  the value in a default format
        when printing structs, the plus flag (%+v) adds field names        
    %#v a Go-syntax representation of the value
    %T  a Go-syntax representation of the type of the value
    %%  a literal percent sign; consumes no value
​
...

可以使用go help doc查看doc命令的详细说明。

使用说明

语法格式：

go doc [doc flags] [package|[package.]symbol[.methodOrField]]

doc flags是doc命令参数，而后续内容是所需查询的对象。go doc会将所需查询对象的文档注释打印出来。这个对象可以是一个包、常量、变量、方法、结构体字段。

• doc支持0~2个参数，当不填入参数时，会将当前所在文件夹的包信息打印出来。
• doc会优先匹配GOROOT和GOPATH中的包名，如果不能找到则会在当前路径寻找。

参数说明：

• -all：展示包的所有注释文档。
• -c：匹配标记时大小写敏感。
• -cmd：像普通包一样处理命令。当展示包顶级注释文档时，隐藏可导出标记。
• -short：每个标记使用一行表示，可以方便的查看可导出标记。
• -src：导出源码，可能会包含一些不可导出的内容。
• -u：同时展示不可导出的部分。

官方示例及说明：

• go doc：展示当前路径下的包的注释文档。
• go doc Foo：展示当前路径下的Foo函数注释文档。因为Foo以大写字母开头。
• go doc encoding/json或者go doc json：展示encoding/json包的注释文档。
• go doc json.Number或者go doc json.number：展示json.Number的注释文档。
• go doc json.Number.Int64或者go doc json.number.int64：展示json.Number的int64方法。
• go doc cmd/doc：展示doc命令的说明文档。
• go doc -cmd doc：展示doc命令的注释文档和可导出标记(包括首字母大写的函数、方法、常量、变量等)
• go doc template.new：展示html/tmplate的New函数，因为html/tmplate在字典序上位于text/tmplate前。
• go doc text/template.new或者go doc text/template new：展示text/template的New函数的文档注释。

书写文档描述

补充：

• 单行注释

  最常见的一种注释方式，以//开始，后面的内容均为注释。

  // 单行注释在此
  

• 多行注释

  以/* */包裹的内容，为多行注释。中间可以随意进行换行。

  /*
      我是多行注释
      的内容
  */
  

  一个有意思的用法，可以快速开关代码的注释。由于IDE工具的快捷键注释功能，这个技巧已经不常用了。

   /* 在这里增加一个'/'既可以解开注释
      需要动态管理的代码段
  //*/
  

文档描述:

• 包描述

  紧挨着package关键字，一般Package开头。用于描述包的作用，特点等信息。

  // Package name is ...
  package name 
  

  推荐使用单独一个doc.go文件作为包描述文件，文件内容仅包含包描述和包声明。

• 函数描述

  紧靠func上方（不相邻的注释会被忽略掉），一般以函数名开头。用于描述函数的功能、特点、用法等信息。变量、常量等的注释文档描述方式也一样。

  // SomeName is used to ...
  func SomeName() {
      ...
  }
  

  • 如果由已知的bug，可以使用Bug()标记。

    // BUG(src): 这段注释不会和Title绑定，但是会进入bugs区
    ​
    // BUG(rsc): The rule Title uses for word boundaries does not handle Unicode 
    // punctuation properly.
    func Title(s []byte) []byte {
        ....
    

  • 如果是需要启用的内容，可以使用Deprecated标记。

    // Deprecated: Use strings.HasPrefix instead.
    

• 示例描述

  • 文件必须放在当前包下
  • 文件名以example开头, _连接, test结尾, 如:example_xxx_test.go
  • 包名是当前包名 + _test, 如: strings_test
  • 函数名称的格式func Example[FuncName][_tag]()
  • 函数注释会展示在页面上
  • 函数结尾加上// Output:注释, 说明函数返回的值

godoc工具

godoc和go doc不一样。

godoc一个小型的go文档服务器工具，可以在网络受限条件下方便的产看go文档。使用方法如下：

下载：

go get -u golang.org/x/tools/cmd/godoc
或者
go install golang.org/x/tools/cmd/godoc

运行：

godoc -http=:8080

此时就可以通过浏览器访问本地8080端口查看共文档了。