High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
docs: add API comment format guide for structured endpoint documentation
Mario307ca41e3b44
diff --git a/scripts/API_COMMENT_FORMAT.md b/scripts/API_COMMENT_FORMAT.mdnew file mode 100644index 00000000..a4c27adc--- /dev/null+++ b/scripts/API_COMMENT_FORMAT.md@@ -0,0 +1,159 @@+# API Documentation Comment Format++This guide shows how to add documentation to handler functions that will be auto-extracted.++## Format++Add structured comments above handler functions using this format:++```go+// HandleSnapshot returns the accessibility tree of the current tab.+//+// @Endpoint GET /snapshot+// @Description Returns the page structure with clickable elements+//+// @Param tabId string query The tab ID (required)+// @Param filter string query Filter: "interactive" or "all" (optional, default: "all")+// @Param interactive bool query Show only interactive elements (optional)+//+// @Response 200 application/json Returns accessibility tree+//+// @Example curl:+// curl "http://localhost:9867/snapshot?tabId=abc123&filter=interactive"+//+// @Example cli:+// pinchtab snap -i -c+//+// @Example python:+// import requests+// response = requests.get("http://localhost:9867/snapshot", params={"tabId": "abc123"})+func (h *Handlers) HandleSnapshot(w http.ResponseWriter, r *http.Request) {+```++## Tags++| Tag | Description | Example |+|-----|-------------|---------|+| `@Endpoint` | HTTP method and path | `@Endpoint GET /snapshot` |+| `@Description` | Brief description | `@Description Returns page structure` |+| `@Param` | Query/body parameter | `@Param tabId string query Tab ID (required)` |+| `@Response` | Response format | `@Response 200 application/json Returns data` |+| `@Example curl:` | cURL example | `curl "http://localhost:9867/snapshot?..."` |+| `@Example cli:` | CLI example | `pinchtab snap -i` |+| `@Example python:` | Python example | `import requests; ...` |+| `@Example javascript:` | JavaScript example | `fetch("http://...").then(...)` |++## Parameter Format++```+@Param {name} {type} {location} {description}+```++- `name`: Parameter name+- `type`: Data type (string, int, bool, json, etc.)+- `location`: Where parameter comes from (query, body, path)+- `description`: Human-readable description + (required/optional, default value)++## Example: Full Handler++```go+// HandleAction performs an action on the current tab (click, type, etc).+//+// @Endpoint POST /action+// @Description Click, type, fill, press, or other actions on page elements+//+// @Param tabId string query The tab ID (required)+// @Param kind string body Action type: "click", "type", "fill", "press", "hover", "focus", "scroll", "select" (required)+// @Param ref string body Element reference from snapshot (e.g., "e5") (required)+// @Param text string body Text to type or fill (for "type"/"fill" actions)+// @Param value string body Value for "select" action+//+// @Response 200 application/json Returns result+// @Response 400 application/json Invalid parameters+//+// @Example curl click:+// curl -X POST http://localhost:9867/action?tabId=abc123 \+// -H "Content-Type: application/json" \+// -d '{"kind":"click","ref":"e5"}'+//+// @Example curl type:+// curl -X POST http://localhost:9867/action?tabId=abc123 \+// -H "Content-Type: application/json" \+// -d '{"kind":"type","ref":"e3","text":"[email protected]"}'+//+// @Example cli click:+// pinchtab click e5+//+// @Example cli type:+// pinchtab type e3 "[email protected]"+func (h *Handlers) HandleAction(w http.ResponseWriter, r *http.Request) {+```++## How It Works++The doc generator will:+1. Parse Go files looking for handler functions+2. Extract comments using `@` tags+3. Generate complete API documentation with:+ - Parameters and defaults+ - Examples in multiple formats (curl, CLI, Python, JavaScript)+ - Response types+ - Error codes++## Benefits++- ✅ Documentation lives in code (single source of truth)+- ✅ Easy to update when API changes+- ✅ Auto-generates curl examples+- ✅ Auto-generates CLI examples+- ✅ Shows default values+- ✅ Marks required vs optional+- ✅ Multiple language examples++## Starting Points++For now, add comments to these high-value endpoints first:++```+Priority 1 (core operations):+- HandleNavigate (POST /navigate)+- HandleSnapshot (GET /snapshot)+- HandleAction (POST /action)+- HandleText (GET /text)++Priority 2 (instance/profile management):+- handleList (GET /instances, GET /profiles)+- handleLaunchByName (POST /instances/launch)+- handleCreate (POST /profiles/create)++Priority 3 (everything else)+```++## Example: How to Add to HandleNavigate++```go+// HandleNavigate navigates a tab to a URL.+//+// @Endpoint POST /navigate+// @Description Navigate to a URL in a tab or create new tab+//+// @Param tabId string query Tab ID (optional - creates new tab if omitted)+// @Param url string query URL to navigate to (required)+// @Param blockAds bool query Block ads (optional, default: false)+// @Param blockImages bool query Block images (optional, default: false)+// @Param blockMedia bool query Block media (optional, default: false)+//+// @Response 200 application/json Returns {tabId, url, title}+//+// @Example curl navigate existing:+// curl -X POST "http://localhost:9867/navigate?tabId=abc123&url=https://example.com"+//+// @Example curl navigate new:+// curl -X POST "http://localhost:9867/navigate?url=https://example.com"+//+// @Example cli:+// pinchtab nav https://example.com+func (h *Handlers) HandleNavigate(w http.ResponseWriter, r *http.Request) {+```++This way, all documentation is version-controlled in the code itself.