docs: document pin info schema (#87)

Author: seveibar

bun.lock

@@ -19,7 +19,7 @@
         "@docusaurus/types": "3.7.0",
         "@tscircuit/create-snippet-url": "^0.0.8",
         "@tscircuit/footprinter": "^0.0.135",
-        "@tscircuit/math-utils": "^0.0.10",
+        "@tscircuit/math-utils": "^0.0.18",
         "@twind/core": "^1.1.3",
         "posthog-docusaurus": "^2.0.2",
         "repomix": "^0.3.9",
@@ -575,7 +575,7 @@
 
     "@tscircuit/footprinter": ["@tscircuit/footprinter@0.0.135", "", { "dependencies": { "@tscircuit/mm": "^0.0.8", "zod": "^3.23.8" }, "peerDependencies": { "circuit-json": "*" } }, "sha512-+8MasMGTNQL/NINnlWk2v6zw/NDerfdIBG3uqhrTr0r7VOHh4lK1ymTkQR7IeoypkxTIHYGB9wHbOt39XAF3mg=="],
 
-    "@tscircuit/math-utils": ["@tscircuit/math-utils@0.0.10", "", { "peerDependencies": { "typescript": "^5.0.0" } }, "sha512-v8d5AcdTL1Bn856PfKBPt90AvB3Mk92kKhS5pPss6KpdVU9vHaUldZGfzWchQhyPcgvWwiWk2to1NKJGNmxgTg=="],
+    "@tscircuit/math-utils": ["@tscircuit/math-utils@0.0.18", "", { "peerDependencies": { "typescript": "^5.0.0" } }, "sha512-P45v7V/BiVZZjXTUzjWSUsy0M8GpI5o6d+JWhPWE5+JwI/sYZARuLT4e1xzV7LaavEX4GQ0NKG9hKN48xTZJsw=="],
 
     "@tscircuit/mm": ["@tscircuit/mm@0.0.8", "", { "peerDependencies": { "typescript": "^5.0.0" } }, "sha512-nl7nxE7AhARbKuobflI0LUzoir7+wJyvwfPw6bzA/O0Q3YTcH3vBkU/Of+V/fp6ht+AofiCXj7YAH9E446138Q=="],
 

docs/web-apis/datasheet-api.md

@@ -27,11 +27,50 @@ POST /datasheets/get { "datasheet_id": "<uuid>" }
     "datasheet_id": "<uuid>",
     "chip_name": "<name>",
     "datasheet_pdf_urls": ["https://..."],
-    "pin_information": { /* ... */ }
+    "pin_information": [ /* pin objects */ ]
   }
 }
 ```
 
+### Pin Information Schema
+
+Each entry in `pin_information` describes one pin on the device and has the
+following structure:
+
+```json
+{
+  "pin_number": "1",
+  "name": ["VCC"],
+  "description": "Power supply for the device.",
+  "capabilities": ["power"]
+}
+```
+
+`pin_number` is always a string and may include alphanumeric values (e.g. `"1"`
+or `"A1"`). The `name` array contains all aliases for the pin. `description` is
+a human‑readable explanation of the pin's function and `capabilities` enumerates
+how the pin can be used.
+
+### Example Response Snippet
+
+Below is an excerpt from the RP2040 datasheet entry:
+
+```bash
+$ curl https://api.tscircuit.com/datasheets/get?chip_name=RP2040 | jq '.datasheet.pin_information[:1]'
+[
+  {
+    "name": [
+      "IOVDD"
+    ],
+    "pin_number": "1",
+    "description": "Power supply for digital GPIOs, nominal voltage 1.8V to 3.3V.",
+    "capabilities": [
+      "Power Supply (Digital IO)"
+    ]
+  }
+]
+```
+
 ## `/datasheets/create`
 
 Creates a new datasheet entry so it can later be parsed and fetched.

package.json

@@ -33,7 +33,7 @@
     "@docusaurus/types": "3.7.0",
     "@tscircuit/create-snippet-url": "^0.0.8",
     "@tscircuit/footprinter": "^0.0.135",
-    "@tscircuit/math-utils": "^0.0.10",
+    "@tscircuit/math-utils": "^0.0.18",
     "@twind/core": "^1.1.3",
     "posthog-docusaurus": "^2.0.2",
     "repomix": "^0.3.9",