wavelet init

.agent/skills/go-documentation/references/FORMATTING.md

@@ -0,0 +1,85 @@
+# 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 格式化是否正确渲染。