使用godoc快速上手生成易维护的文档

godoc利用函数、结构、包的注释生成文档。同时，可以利用一些约定的文件和函数命名方式，生成更细致的用例。非常方便也编译维护。

安装相关库

代码语言：javascript复制

go install -v golang.org/x/tools/cmd/godoc@latest
go install github.com/princjef/gomarkdoc/cmd/gomarkdoc@latest

运行godoc服务

代码语言：javascript复制

godoc -http=0.0.0.0:8000 -play

此时，可以在浏览器中使用 0.0.0.0:8000查看文档网页。编辑注释和用例会实时更新，刷新网页即可。

<img src="https://share.superpig.win/img_share/20240612/image-20240612144917219_393019.webp" alt="image-20240612144917219" style="zoom:33%;" />

编写包注释

在package xxx，上方可以写包注释，格式为Package PACNAME ......。下面是一个示例：

代码语言：javascript复制

// Package try provides a way to safely execute callback functions and handle panics and errors that may occur.
//
// As a quick start:
//
//	// Example for panic handling
//	resultA := try.Or(func() (int, error) {
//		panic("panic")
//		return 42, nil
//	}, -1)
//	fmt.Println("Result A:", resultA) // Output: Result A: -1
package try

这里类似markdown的语法。

1. 空一行为换行。
2. 使用tab可以标记为代码块。

<img src="https://share.superpig.win/img_share/20240612/image-20240612142636160_726291.webp" alt="image-20240612142636160" style="zoom:50%;" />

编写函数、导出变量、结构体注释

和包注释类似，格式为 // FuncStrucVarName ...。

例：导出变量注释

代码语言：javascript复制

// ErrCallbackPanic is the error type returned when the callback function panics
var ErrCallbackPanic = errors.New("callback panic")

例：导出函数注释

代码语言：javascript复制

// WithError callback returns an error.
// If the callback panics, the panic is returned as an error of type `ErrCallbackPanic`.
// If the callback returns an error, that error is returned. Otherwise, it returns `nil`.
func WithError(callback func() error) (err error) 

同理，仍然可以在注释中使用空行进行换行，使用tab插入代码块。

添加用例

为函数、结构、整个包附带一些用例，可以丰富文档的内容。

<img src="https://share.superpig.win/img_share/20240612/image-20240612145238499_651066.webp" alt="image-20240612145238499" style="zoom:50%;" />

首先，新建文件example_PACNAME_test.go。PACNAME是包名。如example_try_test.go。这里要注意，package为PAC_test而不是PAC。如：package try_test // 不是 package try

然后，再在这个文件中通过特殊的命名规则，为文档添加examples。

为导出函数添加用例

当函数名格式为ExampleFuncName，可为函数添加用例。如下是函数WithError1的一个用例：

代码语言：javascript复制

func ExampleWithError1() {
    result, err := try.WithError1(func() (int, error) {
        // Your callback logic here
        return 42, nil
    })
    if err != nil {
        // if panic occurs, err will be ErrCallbackPanic
        if errors.Is(err, try.ErrCallbackPanic) {
            // callback panic: PANIC INFO, file:/FILEPATH/file_xxx.go line: 17
            fmt.Println("Panic:", err)
            return
        }
        fmt.Println("Error:", err)
        return
    }

    fmt.Println("Result:", result)
    // Output: Result: 42
}

1. ExampleWithError1是识别名称，所有Example开头的函数都会被godoc识别为用例。WithError1是函数的名称。
2. 生成的用例会自动转换为main()函数的表现形式。
3. Output: xxx也是可识别字段。这行注释在godoc中会被消除，而单独以Output的方式显示在下方。

效果：

<img src="https://share.superpig.win/img_share/20240612/image-20240612143435649_280760.webp" alt="image-20240612143435649" style="zoom:50%;" />

为结构添加用例

同理，ExamplePerson_Add，是结构体Person.Add函数的用例。其它规则同上。

多个用例

有时，需要为一个函数添加多个用例，如：

<img src="https://share.superpig.win/img_share/20240612/image-20240612143634964_051662.webp" alt="image-20240612143634964" style="zoom:33%;" />

此时，只需要将用例名改为：

代码语言：javascript复制

func ExampleOr() // 第一个用例
func ExampleOr_second() // 第二个用例
func ExampleOr_third() // 第三个用例
......

其它规则不变。

导出为markdown

利用工具gomarkdoc可将godoc导出为本地markdown。

代码语言：javascript复制

// gomarkdoc pacPath > gen_file_path/filename.md
gomarkdoc ./try > try/godoc.md

函数 callback image share 变量

1 人点赞