go的文档

Posted on Edited on In

背景

go作为一个非常现代的语言,官方提供文档功能,
能够以CLI或是html的方式,
将代码中的注释或代码提取出来,当作文档使用.

简介

相关工具分别有

  1. go doc,负责在命令行的显示
  2. godoc,主要负责网页端的显示

这些工具是如何提取和组织内容的,是否引入了特别的规定等等,是这个笔记的关注点

go doc

是自带在go编译器上的工具.
大致用法

1
go doc [-u] [-c] [package|[package.]symbol[.methodOrField]]
  • 其中u,c等是选项.注意选项如果放在其他内容后方可能会出问题.
  • 所谓symbol是指变量,常量,函数,结构体,接口等等
  • 默认不显示main包的内容

具体用法还要看go的官方指导

1
go help doc

一些选项及其用途

  • all,显示所有文档(默认不显示关于函数的注释,加上all可以显示)
  • c,大小写敏感
  • cmd,将main包视为常规包
  • src 显示完整源代码
  • u,显示不向包外暴露的symbol

使用举例

1
2
3
4
go doc sync.WaitGroup.Add       # 显示定义在sync.WaitGroup上的Add方法
go doc -src sync.WaitGroup.Add  # 显示方法注释的同时,显示源代码
go doc -c sync.WaitGroup.add    # 试图查找一个定义在sync.WaitGroup上的add方法,大小写敏感
go doc -u sync.WaitGroup        # 相比不带u,可以看到结构体WaitGroup内部的小写字段

godoc

在1.12版本后从go编译器中分离,需要手动安装

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

需要将 $GOPATH/bin 加入 $PATH

通常使用起来比较简单

1
godoc -http=:6060

这样能够在 localhost:6060 建立一个web服务器,可供查看注释.

打开后能够看到一个树状结构

  1. TOC
  2. 标准库
    1. 库的列表(然后一math/rand举例)
      1. TOC
      2. Overview
        1. 大致的介绍
        2. 库级别的example
      3. Index
        1. 函数和类的列表
        2. 函数级别example的列表
        3. 源码文件的列表
      4. Examples,完全是上面2.2的快捷方式
  3. 第三方库
    1. 在本地计算机写的包也能出现在这里
  4. 其他

信息来源

go doc 和 godoc 公用同样的消息来源和规则.

符号上方的注释被作为普通文档

符号(函数,结构体,接口等等)上方的注释,会被godoc渲染到非代码框的部分.
一些右侧的(比如结构体对于每个字段的解释)或不合法的(Example函数中没能写出Output关键字),
会被godoc渲染在代码框中.

*_test.go 文件中行如 ExampleXxx 的函数,会被显示为用例

用例函数中以Output为关键词开头的部分,会被渲染出新的Output框中

注释语法的处理

  1. 块注释和行注释都能被提取
  2. 注释和注释间用空行断开,表示不要继续提取,块注释被视为不断开的注释
  3. 多行的注释会被渲染为一行文本
  4. 如果想让文本换行,可以使用一个或多个连续的空白注释
  5. 用例中必须使用Output关键词开头才能渲染出Output框,如果不使用,会和Example代发放在一个框里
  6. Output关键词同一行的其他内容,会被放在Output代码框中
  7. Output关键词所在行必须和后续内容紧邻,不可有空行
  8. Output关键词和后续内容之间的空白注释,会被忽略

自定义包文档

size/calc.go

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
// 不想让外部看到,有空行就会断开摘取

// 简易自定义四则运算包
package size

// 加法
//
//
// 上面的多个空注释行会在结果中表示一个换行
func Add(a, b int) (c int) {
  return a + b // 备注
}

// 减法
// 紧邻的一些注释,会在结果中显示成同一行
// 注释发生改动时,godoc刷新页面即可,无需重启服务器
// 但如果包发生改动,列表的更新无法通过刷新网页完成,只能重启服务器
func Sub(a, b int) (c int) {
  return a - c
}

// 乘法
// 页面上显示时,不会考虑真实的代码顺序
// 排序可能会倾向于靠近example的顺序
func Mul(a, b int) (c int) {
  return a * b
}

// 用于测试-all能不能显示
// 结果: 只有-u可以显示小写的内容
func div(a, b int) (c int) {
  if b == 0 {
    panic("divide by zero")
  }
  return a / b
}

// 自定义结构体
type Test struct {
  A int     // a
  b float64 // b
}

size/calc_test.go

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
package size

import "fmt"

// 以Example开头,才能识别为该函数的例子
func ExampleAdd() {
  result := Add(4, 2)
  fmt.Println("4 + 2 =", result)

  // Output:
  // 此处断开注释,会导致output部分丢失
  // 此处的空行,会被Output部分忽略
  // 4 + 2 = 5
}

func ExampleMul() {
  result := Mul(4, 2)
  fmt.Println("4 * 2 =", result)

  // 输出:
  // 此处不使用Output,页面上无法将结果输出在Output部分
  // 而是直接输出在代码中
  // 4 * 2 = 8
}

// 被测函数是非导出,则例子等于白写
func ExampleDiv() {
  result := div(4, 2)
  fmt.Println("4 / 2 =", result)

  // Output:
  // 4 / 2 = 2
}

func ExampleSub() {
  result := Sub(4, 2)
  fmt.Println("4 - 2 =", result)
  // Output: 只要Output开头即可,后面的内容会写在第二行
  // 4 - 2 = 2
}

参考

  1. 主要参考