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

超级大猪

发布于 2024-06-13 13:47:32

1330

发布于 2024-06-13 13:47:32

文章被收录于专栏：大猪的笔记

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

安装相关库

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

运行godoc服务

godoc -http=0.0.0.0:8000 -play

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

编写包注释

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

// 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(&quot;panic&quot;)
//		return 42, nil
//	}, -1)
//	fmt.Println(&quot;Result A:&quot;, resultA) // Output: Result A: -1
package try

这里类似markdown的语法。

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

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

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

例：导出变量注释

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

例：导出函数注释

// 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插入代码块。

添加用例

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

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

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

为导出函数添加用例

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

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(&quot;Panic:&quot;, err)
            return
        }
        fmt.Println(&quot;Error:&quot;, err)
        return
    }

    fmt.Println(&quot;Result:&quot;, result)
    // Output: Result: 42
}

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

效果：

为结构添加用例

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

多个用例

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

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

func ExampleOr() // &#x7B2C;&#x4E00;&#x4E2A;&#x7528;&#x4F8B;
func ExampleOr_second() // &#x7B2C;&#x4E8C;&#x4E2A;&#x7528;&#x4F8B;
func ExampleOr_third() // &#x7B2C;&#x4E09;&#x4E2A;&#x7528;&#x4F8B;
......

其它规则不变。

导出为markdown

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

// gomarkdoc pacPath &gt; gen_file_path/filename.md
gomarkdoc ./try &gt; try/godoc.md

本文参与腾讯云自媒体同步曝光计划，分享自作者个人站点/博客。

原始发表：2024-06-12 ，如有侵权请联系 cloudcommunity@tencent.com 删除

函数

callback

image

变量

本文分享自作者个人站点/博客前往查看

如有侵权，请联系 cloudcommunity@tencent.com 删除。

本文参与腾讯云自媒体同步曝光计划，欢迎热爱写作的你一起参与！

登录后参与评论

0 条评论

热度