使用godoc快速上手生成易维护的文档
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查看文档网页。编辑注释和用例会实时更新，刷新网页即可。
<img src="https://share.superpig.win/img_share/20240612/image-20240612144917219_393019.webp" alt="image-20240612144917219" style="zoom:33%;" />
编写包注释
在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("panic")
// return 42, nil
// }, -1)
// fmt.Println("Result A:", resultA) // Output: Result A: -1
package try这里类似markdown的语法。
- 空一行为换行。
- 使用tab可以标记为代码块。
<img src="https://share.superpig.win/img_share/20240612/image-20240612142636160_726291.webp" alt="image-20240612142636160" style="zoom:50%;" />
编写函数、导出变量、结构体注释
和包注释类似，格式为 // FuncStrucVarName ...。
例：导出变量注释
// ErrCallbackPanic is the error type returned when the callback function panics
var ErrCallbackPanic = errors.New("callback panic")例：导出函数注释
// 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的一个用例：
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
}ExampleWithError1是识别名称，所有Example开头的函数都会被godoc识别为用例。WithError1是函数的名称。- 生成的用例会自动转换为
main()函数的表现形式。 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%;" />
此时，只需要将用例名改为：
func ExampleOr() // 第一个用例
func ExampleOr_second() // 第二个用例
func ExampleOr_third() // 第三个用例
......其它规则不变。
导出为markdown
利用工具gomarkdoc可将godoc导出为本地markdown。
// gomarkdoc pacPath > gen_file_path/filename.md
gomarkdoc ./try > try/godoc.md