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. 總結