chore: move lengthy source code comments to API.md

Author: bartveneman

API.md

@@ -580,15 +580,32 @@ console.log(nodes[0].text) // "(min-width: 768px)"
 
 ---
 
-## `walk(ast, callback)`
+## `walk(ast, callback, depth?)`
 
-Walk the AST in depth-first order.
+Walk the AST in depth-first order, calling the callback for each node.
 
 ```typescript
-function walk(node: CSSNode, callback: (node: CSSNode, depth: number) => void): void
+function walk(
+	node: CSSNode,
+	callback: (node: CSSNode, depth: number) => void | typeof SKIP | typeof BREAK,
+	depth?: number
+): boolean
 ```
 
-**Example:**
+### Parameters
+
+- **`node`** - The root node to start walking from
+- **`callback`** - Function to call for each node visited. Receives the node and its depth (0 for root).
+  - Return `SKIP` to skip children of current node
+  - Return `BREAK` to stop traversal entirely
+  - Return nothing to continue normal traversal
+- **`depth`** - Starting depth (default: 0)
+
+### Returns
+
+`boolean` - Returns `false` if traversal was stopped with `BREAK`, otherwise `true`
+
+### Example 1: Basic Walking
 
 ```typescript
 import { parse, walk } from '@projectwallace/css-parser'
@@ -607,6 +624,151 @@ walk(ast, (node, depth) => {
 //         IDENTIFIER
 ```
 
+### Example 2: Skip Nested Rules
+
+```typescript
+import { parse, walk, SKIP, STYLE_RULE } from '@projectwallace/css-parser'
+
+const ast = parse('.a { .b { .c { color: red; } } }')
+
+walk(ast, (node) => {
+	if (node.type === STYLE_RULE) {
+		console.log(node.text)
+		return SKIP // Don't visit nested rules
+	}
+})
+// Output: .a { ... }, but not .b or .c
+```
+
+### Example 3: Stop on First Declaration
+
+```typescript
+import { parse, walk, BREAK, DECLARATION } from '@projectwallace/css-parser'
+
+const ast = parse('.a { color: red; margin: 10px; }')
+
+walk(ast, (node) => {
+	if (node.type === DECLARATION) {
+		console.log(node.name)
+		return BREAK // Stop traversal
+	}
+})
+// Output: "color" (stops before "margin")
+```
+
+---
+
+## `traverse(ast, options?)`
+
+Walk the AST in depth-first order, calling enter before visiting children and leave after.
+
+```typescript
+function traverse(
+	node: CSSNode,
+	options?: {
+		enter?: (node: CSSNode) => void | typeof SKIP | typeof BREAK
+		leave?: (node: CSSNode) => void | typeof SKIP | typeof BREAK
+	}
+): boolean
+```
+
+### Parameters
+
+- **`node`** - The root node to start walking from
+- **`options`** - Object with optional enter and leave callback functions
+  - **`enter`** - Called before visiting children
+    - Return `SKIP` to skip children (leave still called)
+    - Return `BREAK` to stop traversal entirely (leave NOT called)
+  - **`leave`** - Called after visiting children
+    - Return `BREAK` to stop traversal
+
+### Returns
+
+`boolean` - Returns `false` if traversal was stopped with `BREAK`, otherwise `true`
+
+### Example 1: Track Context with Enter/Leave
+
+```typescript
+import { parse, traverse, AT_RULE } from '@projectwallace/css-parser'
+
+const ast = parse('@media screen { .a { color: red; } }')
+
+let depth = 0
+traverse(ast, {
+	enter(node) {
+		depth++
+		console.log(`${'  '.repeat(depth)}Entering ${node.type_name}`)
+	},
+	leave(node) {
+		console.log(`${'  '.repeat(depth)}Leaving ${node.type_name}`)
+		depth--
+	}
+})
+```
+
+### Example 2: Skip Media Query Contents
+
+```typescript
+import { parse, traverse, SKIP, AT_RULE } from '@projectwallace/css-parser'
+
+const ast = parse('@media screen { .a { color: red; } }')
+
+let depth = 0
+traverse(ast, {
+	enter(node) {
+		depth++
+		if (node.type === AT_RULE) {
+			console.log('Entering media query at depth', depth)
+			return SKIP // Skip contents but still call leave
+		}
+	},
+	leave(node) {
+		if (node.type === AT_RULE) {
+			console.log('Leaving media query at depth', depth)
+		}
+		depth--
+	}
+})
+// Output:
+// Entering media query at depth 2
+// Leaving media query at depth 2
+```
+
+### Example 3: Context-Aware Processing
+
+```typescript
+import { parse, traverse, STYLE_RULE, AT_RULE } from '@projectwallace/css-parser'
+
+const ast = parse(`
+	.top { color: red; }
+	@media screen {
+		.nested { color: blue; }
+	}
+`)
+
+const context = []
+
+traverse(ast, {
+	enter(node) {
+		if (node.type === AT_RULE) {
+			context.push(`@${node.name}`)
+		} else if (node.type === STYLE_RULE) {
+			const selector = node.first_child.text
+			const ctx = context.length ? ` in ${context.join(' ')}` : ''
+			console.log(`Rule: ${selector}${ctx}`)
+		}
+	},
+	leave(node) {
+		if (node.type === AT_RULE) {
+			context.pop()
+		}
+	}
+})
+// Output:
+// Rule: .top
+// Rule: .nested in @media
+```
+
 ---
 
 ## `tokenize(source, skip_comments?)`

src/css-node.ts

@@ -696,25 +696,12 @@ export class CSSNode {
 	// --- Node Cloning ---
 
 	/**
-	 * Clone this node as a mutable plain JavaScript object
-	 *
-	 * Extracts all properties from the arena into a plain object with children as an array.
-	 * The resulting object can be freely modified.
+	 * Clone this node as a mutable plain JavaScript object with children as arrays.
+	 * See API.md for examples.
 	 *
 	 * @param options - Cloning configuration
 	 * @param options.deep - Recursively clone children (default: true)
 	 * @param options.locations - Include line/column/start/length (default: false)
-	 * @returns Plain object with children as array
-	 *
-	 * @example
-	 * const ast = parse('div { color: red; }')
-	 * const decl = ast.first_child.block.first_child
-	 * const plain = decl.clone()
-	 *
-	 * // Access children as array
-	 * plain.children.length
-	 * plain.children[0]
-	 * plain.children.push(newChild)
 	 */
 	clone(options: CloneOptions = {}): PlainCSSNode {
 		const { deep = true, locations = false } = options

src/walk.ts

@@ -8,34 +8,12 @@ export const BREAK = Symbol('BREAK')
 type WalkCallback = (node: CSSNode, depth: number) => void | typeof SKIP | typeof BREAK
 
 /**
- * Walk the AST in depth-first order, calling the callback for each node
+ * Walk the AST in depth-first order, calling the callback for each node.
+ * Return SKIP to skip children, BREAK to stop traversal. See API.md for examples.
  *
  * @param node - The root node to start walking from
- * @param callback - Function to call for each node visited. Receives the node and its depth (0 for root).
- *                   Return SKIP to skip children of current node, or BREAK to stop traversal entirely.
+ * @param callback - Function called for each node. Receives the node and its depth (0 for root).
  * @param depth - Starting depth (default: 0)
- *
- * @example
- * import { parse, walk, SKIP, BREAK } from '@projectwallace/css-parser'
- *
- * const ast = parse('.a { .b { .c { color: red; } } }')
- *
- * // Skip nested rules
- * walk(ast, (node) => {
- *   if (node.type === STYLE_RULE) {
- *     console.log(node.text)
- *     return SKIP // Don't visit nested rules
- *   }
- * })
- * // Output: .a { ... }, but not .b or .c
- *
- * // Stop on first declaration
- * walk(ast, (node) => {
- *   if (node.type === DECLARATION) {
- *     console.log(node.name)
- *     return BREAK // Stop traversal
- *   }
- * })
  */
 export function walk(node: CSSNode, callback: WalkCallback, depth = 0): boolean {
 	// Call callback for current node
@@ -74,36 +52,11 @@ interface WalkEnterLeaveOptions {
 }
 
 /**
- * Walk the AST in depth-first order, calling enter before visiting children and leave after
+ * Walk the AST in depth-first order, calling enter before visiting children and leave after.
+ * Return SKIP in enter to skip children (leave still called), BREAK to stop (leave NOT called). See API.md for examples.
  *
  * @param node - The root node to start walking from
  * @param options - Object with optional enter and leave callback functions
- * @param options.enter - Called before visiting children. Return SKIP to skip children (leave still called),
- *                        or BREAK to stop traversal entirely (leave NOT called).
- * @param options.leave - Called after visiting children. Return BREAK to stop traversal.
- *
- * @example
- * import { parse, traverse, SKIP, BREAK } from '@projectwallace/css-parser'
- *
- * const ast = parse('@media screen { .a { color: red; } }')
- *
- * // Track context with skip
- * let depth = 0
- * traverse(ast, {
- *   enter(node) {
- *     depth++
- *     if (node.type === AT_RULE) {
- *       console.log('Entering media query at depth', depth)
- *       return SKIP // Skip contents but still call leave
- *     }
- *   },
- *   leave(node) {
- *     if (node.type === AT_RULE) {
- *       console.log('Leaving media query at depth', depth)
- *     }
- *     depth--
- *   }
- * })
  */
 export function traverse(node: CSSNode, { enter = NOOP, leave = NOOP }: WalkEnterLeaveOptions = {}): boolean {
 	// Call enter callback before processing children