docs: nice literal unions (#811)

5 files changed, 128 insertions, 73 deletions

diff --git a/test/scripts/apidoc/signature.debug.ts b/test/scripts/apidoc/signature.debug.ts
new file mode 100644
index 00000000..542224ad
--- /dev/null
+++ b/test/scripts/apidoc/signature.debug.ts
@@ -0,0 +1,16 @@
+/**
+ * This file exists, because vitest doesn't allow me to debug code outside of src and test.
+ * And it's easier to test these features independently from the main project.
+ */
+import { analyzeSignature } from '../../../scripts/apidoc/signature';
+import { loadExampleMethods } from './utils';
+
+/* Run with `pnpm esno test/scripts/apidoc/signature.debug.ts` */
+
+const methods = loadExampleMethods();
+
+Object.entries(methods).forEach(([name, method]) => {
+  console.log('Analyzing: ', name);
+  const result = analyzeSignature(method.signatures[0], null, method.name);
+  console.log('Result: ', result);
+});
diff --git a/test/scripts/apidoc/signature.example.ts b/test/scripts/apidoc/signature.example.ts
index 16dae935..2219b072 100644
--- a/test/scripts/apidoc/signature.example.ts
+++ b/test/scripts/apidoc/signature.example.ts
@@ -1,3 +1,5 @@
+import type { LiteralUnion } from '../../../src/faker';
+
 /**
  * Parameter options type with default from signature.
  */
@@ -114,6 +116,15 @@ export class SignatureTest {
   }
 
   /**
+   * Test with LiteralUnion.
+   *
+   * @param value `'a'` or `'b'`.
+   */
+  literalUnionParamMethod(value: LiteralUnion<'a' | 'b'>): string {
+    return value;
+  }
+
+  /**
    * Test with a function parameters.
    *
    * @param options The function parameter.
diff --git a/test/scripts/apidoc/signature.expected.json b/test/scripts/apidoc/signature.expected.json
index f6e398fe..5e4f913a 100644
--- a/test/scripts/apidoc/signature.expected.json
+++ b/test/scripts/apidoc/signature.expected.json
@@ -1,14 +1,4 @@
 {
-  "noParamMethod": {
-    "name": "noParamMethod",
-    "title": "No Param Method",
-    "description": "<p>Test with no parameters.</p>\n",
-    "parameters": [],
-    "returns": "number",
-    "examples": "<div class=\"language-ts\"><pre v-pre><code>faker<span class=\"token punctuation\">.</span><span class=\"token function\">noParamMethod</span><span class=\"token punctuation\">(</span><span class=\"token punctuation\">)</span><span class=\"token operator\">:</span> <span class=\"token builtin\">number</span>\n</code></pre>\n</div>",
-    "deprecated": false,
-    "seeAlsos": []
-  },
   "defaultBooleanParamMethod": {
     "name": "defaultBooleanParamMethod",
     "title": "Default Boolean Param Method",
@@ -42,6 +32,22 @@
     "deprecated": false,
     "seeAlsos": []
   },
+  "literalUnionParamMethod": {
+    "name": "literalUnionParamMethod",
+    "title": "Literal Union Param Method",
+    "description": "<p>Test with LiteralUnion.</p>\n",
+    "parameters": [
+      {
+        "name": "value",
+        "type": "\"a\" | \"b\" | string",
+        "description": "<p><code>'a'</code> or <code>'b'</code>.</p>\n"
+      }
+    ],
+    "returns": "string",
+    "examples": "<div class=\"language-ts\"><pre v-pre><code>faker<span class=\"token punctuation\">.</span><span class=\"token function\">literalUnionParamMethod</span><span class=\"token punctuation\">(</span>value<span class=\"token operator\">:</span> <span class=\"token string\">\"a\"</span> <span class=\"token operator\">|</span> <span class=\"token string\">\"b\"</span> <span class=\"token operator\">|</span> <span class=\"token builtin\">string</span><span class=\"token punctuation\">)</span><span class=\"token operator\">:</span> <span class=\"token builtin\">string</span>\n</code></pre>\n</div>",
+    "deprecated": false,
+    "seeAlsos": []
+  },
   "methodWithDeprecated": {
     "name": "methodWithDeprecated",
     "title": "Method With Deprecated",
@@ -89,6 +95,32 @@
     "deprecated": false,
     "seeAlsos": []
   },
+  "noParamMethod": {
+    "name": "noParamMethod",
+    "title": "No Param Method",
+    "description": "<p>Test with no parameters.</p>\n",
+    "parameters": [],
+    "returns": "number",
+    "examples": "<div class=\"language-ts\"><pre v-pre><code>faker<span class=\"token punctuation\">.</span><span class=\"token function\">noParamMethod</span><span class=\"token punctuation\">(</span><span class=\"token punctuation\">)</span><span class=\"token operator\">:</span> <span class=\"token builtin\">number</span>\n</code></pre>\n</div>",
+    "deprecated": false,
+    "seeAlsos": []
+  },
+  "optionalStringParamMethod": {
+    "name": "optionalStringParamMethod",
+    "title": "Optional String Param Method",
+    "description": "<p>Test with an optional parameter.</p>\n",
+    "parameters": [
+      {
+        "name": "b?",
+        "type": "string",
+        "description": "<p>The string parameter.</p>\n"
+      }
+    ],
+    "returns": "number",
+    "examples": "<div class=\"language-ts\"><pre v-pre><code>faker<span class=\"token punctuation\">.</span><span class=\"token function\">optionalStringParamMethod</span><span class=\"token punctuation\">(</span>b<span class=\"token operator\">?</span><span class=\"token operator\">:</span> <span class=\"token builtin\">string</span><span class=\"token punctuation\">)</span><span class=\"token operator\">:</span> <span class=\"token builtin\">number</span>\n</code></pre>\n</div>",
+    "deprecated": false,
+    "seeAlsos": []
+  },
   "optionsInlineParamMethodWithDefaults": {
     "name": "optionsInlineParamMethodWithDefaults",
     "title": "Options Inline Param Method With Defaults",
@@ -161,50 +193,6 @@
     "deprecated": false,
     "seeAlsos": []
   },
-  "optionsTypeParamMethodWithDefaults": {
-    "name": "optionsTypeParamMethodWithDefaults",
-    "title": "Options Type Param Method With Defaults",
-    "description": "<p>Test with a function parameters with defaults.</p>\n",
-    "parameters": [
-      {
-        "name": "a",
-        "type": "ParameterOptionsTypeA",
-        "default": "{ value: 1 }",
-        "description": "<p>Parameter with signature default.</p>\n"
-      },
-      {
-        "name": "b",
-        "type": "ParameterOptionsTypeB",
-        "default": "{ value: 1 }",
-        "description": "<p>Parameter with jsdocs default.</p>\n"
-      },
-      {
-        "name": "c",
-        "type": "ParameterOptionsTypeC",
-        "description": "<p>Parameter with inner jsdocs default.</p>\n"
-      }
-    ],
-    "returns": "number",
-    "examples": "<div class=\"language-ts\"><pre v-pre><code>faker<span class=\"token punctuation\">.</span><span class=\"token function\">optionsTypeParamMethodWithDefaults</span><span class=\"token punctuation\">(</span>a<span class=\"token operator\">:</span> ParameterOptionsTypeA <span class=\"token operator\">=</span> <span class=\"token punctuation\">{</span> value<span class=\"token operator\">:</span> <span class=\"token number\">1</span> <span class=\"token punctuation\">}</span><span class=\"token punctuation\">,</span> b<span class=\"token operator\">:</span> ParameterOptionsTypeB <span class=\"token operator\">=</span> <span class=\"token punctuation\">{</span> value<span class=\"token operator\">:</span> <span class=\"token number\">1</span> <span class=\"token punctuation\">}</span><span class=\"token punctuation\">,</span> c<span class=\"token operator\">:</span> ParameterOptionsTypeC<span class=\"token punctuation\">)</span><span class=\"token operator\">:</span> <span class=\"token builtin\">number</span>\n</code></pre>\n</div>",
-    "deprecated": false,
-    "seeAlsos": []
-  },
-  "optionalStringParamMethod": {
-    "name": "optionalStringParamMethod",
-    "title": "Optional String Param Method",
-    "description": "<p>Test with an optional parameter.</p>\n",
-    "parameters": [
-      {
-        "name": "b?",
-        "type": "string",
-        "description": "<p>The string parameter.</p>\n"
-      }
-    ],
-    "returns": "number",
-    "examples": "<div class=\"language-ts\"><pre v-pre><code>faker<span class=\"token punctuation\">.</span><span class=\"token function\">optionalStringParamMethod</span><span class=\"token punctuation\">(</span>b<span class=\"token operator\">?</span><span class=\"token operator\">:</span> <span class=\"token builtin\">string</span><span class=\"token punctuation\">)</span><span class=\"token operator\">:</span> <span class=\"token builtin\">number</span>\n</code></pre>\n</div>",
-    "deprecated": false,
-    "seeAlsos": []
-  },
   "optionsParamMethod": {
     "name": "optionsParamMethod",
     "title": "Options Param Method",
@@ -241,6 +229,34 @@
     "deprecated": false,
     "seeAlsos": []
   },
+  "optionsTypeParamMethodWithDefaults": {
+    "name": "optionsTypeParamMethodWithDefaults",
+    "title": "Options Type Param Method With Defaults",
+    "description": "<p>Test with a function parameters with defaults.</p>\n",
+    "parameters": [
+      {
+        "name": "a",
+        "type": "ParameterOptionsTypeA",
+        "default": "{ value: 1 }",
+        "description": "<p>Parameter with signature default.</p>\n"
+      },
+      {
+        "name": "b",
+        "type": "ParameterOptionsTypeB",
+        "default": "{ value: 1 }",
+        "description": "<p>Parameter with jsdocs default.</p>\n"
+      },
+      {
+        "name": "c",
+        "type": "ParameterOptionsTypeC",
+        "description": "<p>Parameter with inner jsdocs default.</p>\n"
+      }
+    ],
+    "returns": "number",
+    "examples": "<div class=\"language-ts\"><pre v-pre><code>faker<span class=\"token punctuation\">.</span><span class=\"token function\">optionsTypeParamMethodWithDefaults</span><span class=\"token punctuation\">(</span>a<span class=\"token operator\">:</span> ParameterOptionsTypeA <span class=\"token operator\">=</span> <span class=\"token punctuation\">{</span> value<span class=\"token operator\">:</span> <span class=\"token number\">1</span> <span class=\"token punctuation\">}</span><span class=\"token punctuation\">,</span> b<span class=\"token operator\">:</span> ParameterOptionsTypeB <span class=\"token operator\">=</span> <span class=\"token punctuation\">{</span> value<span class=\"token operator\">:</span> <span class=\"token number\">1</span> <span class=\"token punctuation\">}</span><span class=\"token punctuation\">,</span> c<span class=\"token operator\">:</span> ParameterOptionsTypeC<span class=\"token punctuation\">)</span><span class=\"token operator\">:</span> <span class=\"token builtin\">number</span>\n</code></pre>\n</div>",
+    "deprecated": false,
+    "seeAlsos": []
+  },
   "requiredNumberParamMethod": {
     "name": "requiredNumberParamMethod",
     "title": "Required Number Param Method",
diff --git a/test/scripts/apidoc/signature.spec.ts b/test/scripts/apidoc/signature.spec.ts
index d550dfd2..427ed923 100644
--- a/test/scripts/apidoc/signature.spec.ts
+++ b/test/scripts/apidoc/signature.spec.ts
@@ -1,12 +1,12 @@
 import { writeFileSync } from 'fs';
 import { resolve } from 'path';
-import * as TypeDoc from 'typedoc';
 import { afterAll, describe, expect, it } from 'vitest';
 import type { Method } from '../../../docs/.vitepress/components/api-docs/method';
 import { analyzeSignature } from '../../../scripts/apidoc/signature';
-import { newTypeDocApp, patchProject } from '../../../scripts/apidoc/utils';
 import { SignatureTest } from './signature.example';
 import expected_ from './signature.expected.json';
+import { loadExampleMethods } from './utils';
+
 const expected: Record<string, Method> = expected_;
 
 function prettyJson(object): string {
@@ -14,24 +14,9 @@ function prettyJson(object): string {
 }
 
 describe('signature', () => {
-  const app = newTypeDocApp();
-
-  app.bootstrap({
-    entryPoints: ['test/scripts/apidoc/signature.example.ts'],
-    tsconfig: 'test/scripts/apidoc/tsconfig.json',
-  });
-
-  const project = app.convert();
-
-  patchProject(project);
-
-  const methods: Record<string, TypeDoc.DeclarationReflection> = project
-    .getChildrenByKind(TypeDoc.ReflectionKind.Class)[0]
-    .getChildrenByKind(TypeDoc.ReflectionKind.Method)
-    .reduce((a, v) => ({ ...a, [v.name]: v }), {});
-
   describe('analyzeSignature()', () => {
     const actuals = {};
+    const methods = loadExampleMethods();
 
     it('dummy dependency to rerun the test if the example changes', () => {
       expect(new SignatureTest()).toBeTruthy();
@@ -41,8 +26,9 @@ describe('signature', () => {
       expect(Object.keys(methods).sort()).toEqual(Object.keys(expected).sort());
     });
 
-    it.each(Object.keys(expected))('%s', (name) => {
+    it.each(Object.keys(expected).sort())('%s', (name) => {
       const method = methods[name];
+      expect(method, `Method ${name} to be defined`).toBeDefined();
       const actual = analyzeSignature(method.signatures[0], null, method.name);
       actuals[name] = actual;
 
diff --git a/test/scripts/apidoc/utils.ts b/test/scripts/apidoc/utils.ts
new file mode 100644
index 00000000..d4d11e8c
--- /dev/null
+++ b/test/scripts/apidoc/utils.ts
@@ -0,0 +1,26 @@
+import type { DeclarationReflection } from 'typedoc';
+import { ReflectionKind } from 'typedoc';
+import { newTypeDocApp, patchProject } from '../../../scripts/apidoc/utils';
+
+/**
+ * Loads the example methods using TypeDoc.
+ */
+export function loadExampleMethods(): Record<string, DeclarationReflection> {
+  const app = newTypeDocApp();
+
+  app.bootstrap({
+    entryPoints: ['test/scripts/apidoc/signature.example.ts'],
+    tsconfig: 'test/scripts/apidoc/tsconfig.json',
+  });
+
+  const project = app.convert();
+
+  patchProject(project);
+
+  const methods: Record<string, DeclarationReflection> = project
+    .getChildrenByKind(ReflectionKind.Class)[0]
+    .getChildrenByKind(ReflectionKind.Method)
+    .reduce((a, v) => ({ ...a, [v.name]: v }), {});
+
+  return methods;
+}