2025年7月14日 02:01:37 星期一

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

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

安装相关库

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

运行godoc服务

  1. godoc -http=0.0.0.0:8000 -play

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

image-20240612144917219

编写包注释

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

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

这里类似markdown的语法。

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

image-20240612142636160

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

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

例:导出变量注释

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

例:导出函数注释

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

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

添加用例

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

image-20240612145238499

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

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

为导出函数添加用例

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

  1. func ExampleWithError1() {
  2. result, err := try.WithError1(func() (int, error) {
  3. // Your callback logic here
  4. return 42, nil
  5. })
  6. if err != nil {
  7. // if panic occurs, err will be ErrCallbackPanic
  8. if errors.Is(err, try.ErrCallbackPanic) {
  9. // callback panic: PANIC INFO, file:/FILEPATH/file_xxx.go line: 17
  10. fmt.Println("Panic:", err)
  11. return
  12. }
  13. fmt.Println("Error:", err)
  14. return
  15. }
  16. fmt.Println("Result:", result)
  17. // Output: Result: 42
  18. }
  1. ExampleWithError1是识别名称,所有Example开头的函数都会被godoc识别为用例。WithError1是函数的名称。
  2. 生成的用例会自动转换为main()函数的表现形式。
  3. Output: xxx也是可识别字段。这行注释在godoc中会被消除,而单独以Output的方式显示在下方。

效果:

image-20240612143435649

为结构添加用例

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

多个用例

有时,需要为一个函数添加多个用例,如:

image-20240612143634964

此时,只需要将用例名改为:

  1. func ExampleOr() // 第一个用例
  2. func ExampleOr_second() // 第二个用例
  3. func ExampleOr_third() // 第三个用例
  4. ......

其它规则不变。

导出为markdown

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

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

来自 大脸猪 写于 2024-06-12 15:00 -- 更新于2024-06-13 15:37 -- 0 条评论

0条评论

字体
字号


评论: