init: claude

claude/commands/write-godoc.md

@@ -0,0 +1,87 @@
+---
+allowed-tools: Bash(gh issue:*), Bash(gh api:*), Bash(gh milestone:*), Bash(bun run:*), Bash(echo *)
+description: Write Go Specific Documentation
+---
+
+Write and update Go documentation comments for all Go source files in the directory path specified by $ARGUMENTS, following the latest Go documentation standards and our project conventions.
+
+## Steps
+
+1. **Scan the directory at path `$ARGUMENTS` for all `.go` source files.**
+2. **For each Go file found:**
+   - Add or improve package-level doc comments.
+     - Place the main package comment directly above the `package` declaration, or in a dedicated `doc.go` file for large overviews.
+     - The first sentence should summarize the package and will be used as its synopsis.
+   - For each exported function, method, type, variable, and constant:
+     - Write a doc comment immediately preceding its declaration, with no intervening blank line.
+     - Start the comment with the name of the item being documented.
+     - Use clear, complete sentences that explain what the item does, its purpose, and any important details.
+     - For deprecated items, add a paragraph starting with `Deprecated:` and explain the deprecation.
+     - For known issues, add a comment starting with `BUG(username):` to be included in the “Bugs” section.
+   - For struct fields, add comments if they are exported and not self-explanatory.
+   - For HTTP handlers using swaggo/swag, format docstrings according to swaggo’s OpenAPI requirements.
+3. **Formatting and Style:**
+   - Write comments as you would want to read them, even if godoc didn’t exist.
+   - Use proper Go doc formatting:
+     - Separate paragraphs with a blank line.
+     - Indent pre-formatted text.
+     - URLs will be auto-linked; no special markup needed.
+   - Avoid documenting unexported (private) identifiers unless necessary for maintainers.
+   - Do not modify code logic or formatting—only add or update doc comments.
+4. **Save changes directly to the source files.**
+5. **Confirm completion with a message.**
+
+## Requirements
+
+- Prioritize clear, concise, and idiomatic Go documentation.
+- Use `mcp__godoc_search` to find relevant Go code examples or documentation patterns.
+- If unfamiliar with a package or function, prompt for additional context before proceeding.
+- Do not document non-Go files or unrelated assets.
+- Follow existing project documentation and coding standards.
+
+## When Writing API Handlers
+
+- Use swaggo/swag comment structure for all echo HTTP Handlers to generate OpenAPI-compatible documentation.
+- Include parameter, response, and summary annotations as required by swaggo.
+
+### Example Swaggo Docs
+
+```go
+// ShowAccount godoc
+// @Summary Show an account
+// @Description get string by ID
+// @Tags accounts
+// @Accept json
+// @Produce json
+// @Param id path int true "Account ID"
+// @Success 200 {object} model.Account
+// @Failure 400 {object} httputil.HTTPError
+// @Failure 404 {object} httputil.HTTPError
+// @Failure 500 {object} httputil.HTTPError
+// @Router /accounts/{id} [get]
+func (c *Controller) ListAccounts(ctx echo.Context) {
+q := ctx.Request.URL.Query().Get("q")
+accounts, err := model.AccountsAll(q)
+if err != nil {
+httputil.NewError(ctx, http.StatusNotFound, err)
+return
+}
+ctx.JSON(http.StatusOK, accounts)
+}
+//...
+```
+
+## Best Practices (from official Go guidelines)
+
+- Comments for exported identifiers should begin with the name of the identifier.
+- The first sentence should be a concise summary, suitable for display in package listings.
+- Use full sentences and proper punctuation.
+- For large package overviews, use a dedicated `doc.go` file.
+- Mark deprecated items with `Deprecated:` and known bugs with `BUG(username):`.
+- Keep comments up to date as code evolves.
+
+## References
+
+- [Go Doc Comments (Official Guide)](https://go.dev/doc/comment)
+- [Godoc: documenting Go code (Go Blog)](https://go.dev/blog/godoc)
+- [swaggo/swag Documentation](https://github.com/swaggo/swag)