使用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`查看文档网页。编辑注释和用例会实时更新，刷新网页即可。

## 编写包注释

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

```go
// 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可以标记为代码块。

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

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

例：导出变量注释

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

例：导出函数注释

```go
// 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`的一个用例：

```go
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的方式显示在下方。

效果：

#### 为结构添加用例

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

#### 多个用例

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

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

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

其它规则不变。

## 导出为markdown

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

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

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

大猪 & 大兔

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

0条评论

评论:

文章分类

相册

关于网站

友情链接