Group overloads

apps/website/scripts/jsdoc.mjs

@@ -6,6 +6,7 @@ import * as babelParser from '@babel/parser';
 import { parse as parseComment } from 'comment-parser';
 import { asyncWalk } from 'estree-walker';
 import prettier from 'prettier';
+import { groupBy } from 'lodash-es';
 
 const files = await promisify(glob)('../../packages/*/src/**/*.ts', {
   absolute: true,
@@ -88,11 +89,14 @@ await Promise.all(
               )
             );
 
+            const overloadTag = doc.tags.find((tag) => tag.tag === 'overload');
+
             packageApis.push({
               kind,
               name,
               description: doc.description,
               examples,
+              alias: overloadTag?.name,
             });
           }
         },
@@ -106,22 +110,35 @@ for (const [packageName, packageApis] of apis) {
     continue;
   }
 
+  const groupedApis = groupBy(packageApis, (api) => api.name);
+
   const filePath = resolve('docs', packageName, 'api.md');
 
-  const content = [
-    '# APIs',
-    'Full list of available APIs.',
-    ...packageApis.flatMap((api) =>
-      [
-        `## \`${api.name}\` ${
-          api.kind === 'type' ? '<Badge text="TypeScript only" />' : ''
-        }`,
-        ,
-        api.description,
-        ...api.examples.map((example) => '```ts\n' + example + '\n```'),
-      ].filter(Boolean)
-    ),
-  ].join('\n\n');
-
-  await writeFile(filePath, content);
+  const content = ['# APIs', 'Full list of available APIs.'];
+
+  for (const [name, overloads] of Object.entries(groupedApis)) {
+    const tsOnly = overloads.every((api) => api.kind === 'type');
+    content.push(
+      `## \`${name}\` ${tsOnly ? '<Badge text="TypeScript only" />' : ''}`
+    );
+
+    if (overloads.length === 1) {
+      const [onlyOverload] = overloads;
+      content.push(onlyOverload.description);
+      content.push(
+        ...onlyOverload.examples.map((example) => '```ts\n' + example + '\n```')
+      );
+    } else {
+      content.push('Is has multiple overloads 👇');
+      for (const overload of overloads) {
+        content.push(`### \`${overload.alias ?? overload.name}\``);
+        content.push(overload.description);
+        content.push(
+          ...overload.examples.map((example) => '```ts\n' + example + '\n```')
+        );
+      }
+    }
+  }
+
+  await writeFile(filePath, content.join('\n\n'));
 }

package.json

@@ -47,6 +47,7 @@
   "dependencies": {
     "@algolia/client-search": "^4.14.3",
     "bytes": "^3.1.2",
+    "lodash-es": "^4.17.21",
     "pretty-bytes": "^6.1.1",
     "sandpack-vue3": "^3.1.7"
   }

packages/contracts/src/index.ts

@@ -163,6 +163,8 @@ export function and<T>(
 
 /**
  * Function that creates a _Contract_ that checks if a value is object and every property is conform to the given _Contract_.
+ * 
+ * @overload "rec(str, contract)"
  *
  * @example
  * const Ids = rec(str, num);
@@ -178,6 +180,8 @@ export function rec<V>(
 /**
  * Function that creates a _Contract_ that checks if a value is conform to an object with the given _Contracts_ as properties.
  *
+ * @overload "rec(shape)"
+ * 
  * @example
  * const User = rec({
  *  name: str,