mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-09-28 05:46:36 +08:00
ryan
86 lines
1.6 KiB
Markdown
86 lines
1.6 KiB
Markdown
# 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 格式化是否正确渲染。
|