# Godoc 格式化参考

## Godoc 格式化

> **建议**：使用 godoc 语法编写格式良好的文档。

**段落** - 用空行分隔：

```go
// 好：
// LoadConfig reads a configuration out of the named file.
//
// See some/shortlink for config file format details.
```

**逐字/代码块** - 额外缩进两个空格：

```go
// 好：
// Update runs the function in an atomic transaction.
//
// This is typically used with an anonymous TransactionFunc:
//
//   if err := db.Update(func(state *State) { state.Foo = bar }); err != nil {
//     //...
//   }
```

**列表和表格** - 使用逐字格式：

```go
// 好：
// LoadConfig treats the following keys in special ways:
//   "import" will make this configuration inherit from the named file.
//   "env" if present will be populated with the system environment.
```

**标题** - 单行，首字母大写，无标点（括号/逗号除外），后跟段落：

```go
// 好：
// Using headings
//
// Headings come with autogenerated anchor tags for easy linking.
```

---

## 信号增强

> **建议**：添加注释以突出不寻常或容易被忽略的模式。

以下两种情况很难区分：

```go
if err := doSomething(); err != nil {  // 常见
    // ...
}

if err := doSomething(); err == nil {  // 不寻常！
    // ...
}
```

添加注释来增强信号：

```go
// 好：
if err := doSomething(); err == nil { // 如果没有错误
    // ...
}
```

---

## 文档预览

> **建议**：在代码审查之前和期间预览文档。

```bash
go install golang.org/x/pkgsite/cmd/pkgsite@latest
pkgsite
```

这可以验证 godoc 格式化是否正确渲染。