OpenFlare/.agents/skills/go-documentation/references/FORMATTING.md

Godoc 格式化参考

Godoc 格式化

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

段落 - 用空行分隔：

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

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

// 好：
// 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 {
//     //...
//   }

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

// 好：
// 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.

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

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

---

信号增强

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

以下两种情况很难区分：

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

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

添加注释来增强信号：

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

---

文档预览

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

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

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