Go 文档生成与示例代码

对应视频 8-6 生成文档和示例代码

1. godoc 文档生成

Go 的文档直接从源码注释中提取，不需要特殊标记语法。

1.1 注释规范

// Package queue 实现了一个简单的 FIFO 队列。
//
// 该队列基于切片实现，支持 Push、Pop 和 IsEmpty 操作。
package queue

// Queue 代表一个整数先进先出队列。
type Queue []int

// Push 将元素 v 添加到队列尾部。
func (q *Queue) Push(v int) {
    *q = append(*q, v)
}

// Pop 移除并返回队列头部的元素。
// 如果队列为空，会 panic。
func (q *Queue) Pop() int {
    head := (*q)[0]
    *q = (*q)[1:]
    return head
}

// IsEmpty 返回队列是否为空。
func (q *Queue) IsEmpty() bool {
    return len(*q) == 0
}

规则：
- 注释紧贴在声明上方，以被注释对象的名称开头
- 包注释写在 package 语句上方（或单独的 doc.go 文件中）
- 空行分隔段落
- 缩进的文本会被当作代码块显示

1.2 查看文档

# 本地启动 godoc 服务（Go 1.12 之前内置，之后需安装）
go install golang.org/x/tools/cmd/godoc@latest
godoc -http :6060
# 浏览器访问 http://localhost:6060

# 命令行查看
go doc fmt
go doc fmt.Println
go doc -all queue       # 查看包的所有文档

1.3 pkg.go.dev

发布到 GitHub 的包会自动在 pkg.go.dev 上生成文档，无需额外操作。

2. Example 测试（可执行的文档）

Example 函数既是文档又是测试，写在 _test.go 文件中：

// queue_test.go
package queue_test

import (
    "fmt"
    "myproject/queue"
)

// 包级别的示例
func Example() {
    q := queue.Queue{1}
    q.Push(2)
    q.Push(3)
    fmt.Println(q.Pop())
    fmt.Println(q.Pop())
    fmt.Println(q.IsEmpty())
    // Output:
    // 1
    // 2
    // false
}

// 方法级别的示例
func ExampleQueue_Push() {
    var q queue.Queue
    q.Push(1)
    q.Push(2)
    fmt.Println(q)
    // Output:
    // [1 2]
}

func ExampleQueue_IsEmpty() {
    var q queue.Queue
    fmt.Println(q.IsEmpty())
    q.Push(1)
    fmt.Println(q.IsEmpty())
    // Output:
    // true
    // false
}

命名规则

Output 注释

• // Output: — 精确匹配输出
• // Unordered output: — 不关心输出顺序（适合 map 遍历等）
• 没有 Output 注释 → 只编译不运行（仅检查编译通过）

# 运行示例测试
go test -v -run Example

运行 godoc 时，Example 函数会自动显示在对应函数/类型的文档页面中，并且带有可运行按钮。

3. go generate

go generate 用于在编译前运行代码生成工具。

3.1 基本用法

在 Go 源文件中添加特殊注释：

//go:generate stringer -type=Pill
package painkiller

type Pill int

const (
    Placebo Pill = iota
    Aspirin
    Ibuprofen
    Paracetamol
)

# 安装 stringer 工具
go install golang.org/x/tools/cmd/stringer@latest

# 运行 generate（会执行文件中所有 //go:generate 指令）
go generate ./...

这会自动生成 pill_string.go，包含 Pill 类型的 String() 方法。

3.2 常见的 generate 用途

3.3 Go 1.16+ embed（替代 go-bindata）

package main

import (
    "embed"
    "fmt"
    "net/http"
)

//go:embed static/*
var staticFiles embed.FS

//go:embed config.json
var config []byte

//go:embed version.txt
var version string

func main() {
    fmt.Println("Version:", version)
    fmt.Println("Config:", string(config))

    // 静态文件服务
    http.Handle("/static/",
        http.FileServer(http.FS(staticFiles)))
    http.ListenAndServe(":8080", nil)
}

4. 总结