Add example URLs to JSDoc comments

.gitignore

@@ -8,7 +8,6 @@ Thumbs.db
 *.log
 logs
 *.map
-distribution
 dist
 .cache
 .parcel-cache

add-examples-to-dts.ts

@@ -0,0 +1,51 @@
+#!/usr/bin/env node --experimental-strip-types
+import {readFileSync, writeFileSync} from 'node:fs';
+// Import index.ts to populate the test data via side effect
+// eslint-disable-next-line import/no-unassigned-import, n/file-extension-in-import
+import './index.ts';
+// eslint-disable-next-line n/file-extension-in-import
+import {getTests} from './collector.ts';
+
+// Read the generated .d.ts file
+const dtsPath = './distribution/index.d.ts';
+const dtsContent = readFileSync(dtsPath, 'utf8');
+
+// Process each exported function
+const lines = dtsContent.split('\n');
+const outputLines: string[] = [];
+
+for (const line of lines) {
+	// Check if this is a function declaration
+	const match = /^export declare const (\w+):/.exec(line);
+	if (match) {
+		const functionName = match[1];
+
+		// Get the tests/examples for this function
+		const examples = getTests(functionName);
+
+		// Only add examples if they exist and aren't the special 'combinedTestOnly' marker
+		// 'combinedTestOnly' is used to skip tests for combined functions (e.g., isPageA() || isPageB())
+		if (examples && examples.length > 0 && examples[0] !== 'combinedTestOnly') {
+			// Filter to only include actual URLs (not references to other functions)
+			// getTests() recursively expands function references, so we just need to filter the final list
+			const urlExamples = examples.filter((url: string) => url.startsWith('http'));
+
+			if (urlExamples.length > 0) {
+				// Add JSDoc comment with examples before the declaration
+				outputLines.push('/**');
+				for (const url of urlExamples) {
+					outputLines.push(` * @example ${url}`);
+				}
+
+				outputLines.push(' */');
+			}
+		}
+	}
+
+	outputLines.push(line);
+}
+
+// Write the modified content back
+writeFileSync(dtsPath, outputLines.join('\n'), 'utf8');
+
+console.log('✓ Added example URLs to index.d.ts');

distribution/collector.d.ts

@@ -0,0 +1,5 @@
+/** @file This needs to be in a separate file so it can bee tree-shaken before being published, while still being importable by tests */
+export declare const testableUrls: Map<string, string[]>;
+export declare function addTests(test: string, urls: string[]): void;
+export declare function getTests(detectName: string): string[];
+export declare function getAllUrls(): Set<string>;

distribution/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package.json

@@ -27,6 +27,7 @@
 		"build": "run-p build:*",
 		"build:esbuild": "esbuild index.ts --bundle --external:github-reserved-names --outdir=distribution --format=esm --drop-labels=TEST",
 		"build:typescript": "tsc --declaration --emitDeclarationOnly",
+		"postbuild:typescript": "node --experimental-strip-types add-examples-to-dts.ts",
 		"build:demo": "vite build demo",
 		"try": "esbuild index.ts --bundle --global-name=x --format=iife | pbcopy && echo 'Copied to clipboard'",
 		"fix": "xo --fix",