docs: add test for api docs generation (#574)

test/scripts/apidoc/.gitignore

@@ -0,0 +1 @@
+*.actuals.json

test/scripts/apidoc/signature.example.ts

@@ -0,0 +1,88 @@
+export class SignatureTest {
+  /**
+   * Test with no parameters.
+   */
+  noParamMethod(): number {
+    return 0;
+  }
+
+  /**
+   * Test with a required parameter.
+   *
+   * @param a The number parameter.
+   */
+  requiredNumberParamMethod(a: number): number {
+    return a;
+  }
+
+  /**
+   * Test with an optional parameter.
+   *
+   * @param b The string parameter.
+   */
+  optionalStringParamMethod(b?: string): number {
+    return +b;
+  }
+
+  /**
+   * Test with a default parameter.
+   *
+   * @param c The boolean parameter.
+   */
+  defaultBooleanParamMethod(c: boolean = true): number {
+    return c ? 1 : 0;
+  }
+
+  /**
+   * Test with multiple parameters.
+   *
+   * @param a The number parameter.
+   * @param b The string parameter.
+   * @param c The boolean parameter.
+   */
+  multiParamMethod(a: number, b?: string, c: boolean = true): number {
+    return c ? a : +b;
+  }
+
+  /**
+   * Test with a function parameters.
+   *
+   * @param fn The function parameter.
+   */
+  functionParamMethod(fn: (a: string) => number): number {
+    return fn('a');
+  }
+
+  /**
+   * Test with a function parameters.
+   *
+   * @param options The function parameter.
+   * @param options.a The number parameter.
+   * @param options.b The string parameter.
+   * @param options.c The boolean parameter.
+   */
+  optionsParamMethod(options: { a: number; b?: string; c: boolean }): number {
+    return options.c ? options.a : +options.b;
+  }
+
+  /**
+   * Test with example marker.
+   *
+   * @example
+   * test.apidoc.methodWithExample() // 0
+   */
+  methodWithExample(): number {
+    return 0;
+  }
+
+  /**
+   * Test with deprecated and see marker.
+   *
+   * @see test.apidoc.methodWithExample()
+   *
+   * @deprecated
+   */
+  methodWithDeprecated(): number {
+    return 0;
+  }
+}

test/scripts/apidoc/signature.expected.json

@@ -0,0 +1,155 @@
+{
+  "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",
+    "description": "<p>Test with a default parameter.</p>\n",
+    "parameters": [
+      {
+        "name": "c",
+        "type": "boolean",
+        "default": "true",
+        "description": "<p>The boolean parameter.</p>\n"
+      }
+    ],
+    "returns": "number",
+    "examples": "<div class=\"language-ts\"><pre v-pre><code>faker<span class=\"token punctuation\">.</span><span class=\"token function\">defaultBooleanParamMethod</span><span class=\"token punctuation\">(</span>c<span class=\"token operator\">:</span> <span class=\"token builtin\">boolean</span> <span class=\"token operator\">=</span> <span class=\"token boolean\">true</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": []
+  },
+  "functionParamMethod": {
+    "name": "functionParamMethod",
+    "title": "Function Param Method",
+    "description": "<p>Test with a function parameters.</p>\n",
+    "parameters": [
+      {
+        "name": "fn",
+        "type": "Function",
+        "description": "<p>The function parameter.</p>\n"
+      }
+    ],
+    "returns": "number",
+    "examples": "<div class=\"language-ts\"><pre v-pre><code>faker<span class=\"token punctuation\">.</span><span class=\"token function\">functionParamMethod</span><span class=\"token punctuation\">(</span>fn<span class=\"token operator\">:</span> <span class=\"token builtin\">Function</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": []
+  },
+  "methodWithDeprecated": {
+    "name": "methodWithDeprecated",
+    "title": "Method With Deprecated",
+    "description": "<p>Test with deprecated and see marker.</p>\n",
+    "parameters": [],
+    "returns": "number",
+    "examples": "<div class=\"language-ts\"><pre v-pre><code>faker<span class=\"token punctuation\">.</span><span class=\"token function\">methodWithDeprecated</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": true,
+    "seeAlsos": ["test.apidoc.methodWithExample()"]
+  },
+  "methodWithExample": {
+    "name": "methodWithExample",
+    "title": "Method With Example",
+    "description": "<p>Test with example marker.</p>\n",
+    "parameters": [],
+    "returns": "number",
+    "examples": "<div class=\"language-ts\"><pre v-pre><code>faker<span class=\"token punctuation\">.</span><span class=\"token function\">methodWithExample</span><span class=\"token punctuation\">(</span><span class=\"token punctuation\">)</span><span class=\"token operator\">:</span> <span class=\"token builtin\">number</span>\ntest<span class=\"token punctuation\">.</span>apidoc<span class=\"token punctuation\">.</span><span class=\"token function\">methodWithExample</span><span class=\"token punctuation\">(</span><span class=\"token punctuation\">)</span> <span class=\"token comment\">// 0</span>\n</code></pre>\n</div>",
+    "deprecated": false,
+    "seeAlsos": []
+  },
+  "multiParamMethod": {
+    "name": "multiParamMethod",
+    "title": "Multi Param Method",
+    "description": "<p>Test with multiple parameters.</p>\n",
+    "parameters": [
+      {
+        "name": "a",
+        "type": "number",
+        "description": "<p>The number parameter.</p>\n"
+      },
+      {
+        "name": "b?",
+        "type": "string",
+        "description": "<p>The string parameter.</p>\n"
+      },
+      {
+        "name": "c",
+        "type": "boolean",
+        "default": "true",
+        "description": "<p>The boolean parameter.</p>\n"
+      }
+    ],
+    "returns": "number",
+    "examples": "<div class=\"language-ts\"><pre v-pre><code>faker<span class=\"token punctuation\">.</span><span class=\"token function\">multiParamMethod</span><span class=\"token punctuation\">(</span>a<span class=\"token operator\">:</span> <span class=\"token builtin\">number</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> c<span class=\"token operator\">:</span> <span class=\"token builtin\">boolean</span> <span class=\"token operator\">=</span> <span class=\"token boolean\">true</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": []
+  },
+  "optionsParamMethod": {
+    "name": "optionsParamMethod",
+    "title": "Options Param Method",
+    "description": "<p>Test with a function parameters.</p>\n",
+    "parameters": [
+      {
+        "name": "options",
+        "type": "Object",
+        "description": "<p>The function parameter.</p>\n"
+      },
+      {
+        "name": "options.a",
+        "type": "number",
+        "description": "<p>The number parameter.</p>\n"
+      },
+      {
+        "name": "options.b?",
+        "type": "string",
+        "description": "<p>The string parameter.</p>\n"
+      },
+      {
+        "name": "options.c",
+        "type": "boolean",
+        "description": "<p>The boolean parameter.</p>\n"
+      }
+    ],
+    "returns": "number",
+    "examples": "<div class=\"language-ts\"><pre v-pre><code>faker<span class=\"token punctuation\">.</span><span class=\"token function\">optionsParamMethod</span><span class=\"token punctuation\">(</span>options<span class=\"token operator\">:</span> Object<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",
+    "description": "<p>Test with a required parameter.</p>\n",
+    "parameters": [
+      {
+        "name": "a",
+        "type": "number",
+        "description": "<p>The number parameter.</p>\n"
+      }
+    ],
+    "returns": "number",
+    "examples": "<div class=\"language-ts\"><pre v-pre><code>faker<span class=\"token punctuation\">.</span><span class=\"token function\">requiredNumberParamMethod</span><span class=\"token punctuation\">(</span>a<span class=\"token operator\">:</span> <span class=\"token builtin\">number</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": []
+  }
+}

test/scripts/apidoc/signature.spec.ts

@@ -0,0 +1,53 @@
+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 expected_ from './signature.expected.json';
+const expected: Record<string, Method> = expected_;
+
+function prettyJson(object): string {
+  return JSON.stringify(object, null, 2);
+}
+
+describe('signature', () => {
+  const app = new TypeDoc.Application();
+
+  app.options.addReader(new TypeDoc.TSConfigReader());
+
+  app.bootstrap({
+    entryPoints: ['test/scripts/apidoc/signature.example.ts'],
+    tsconfig: 'test/scripts/apidoc/tsconfig.json',
+  });
+
+  const methods: Record<string, TypeDoc.DeclarationReflection> = app
+    .convert()
+    .getChildrenByKind(TypeDoc.ReflectionKind.Class)[0]
+    .getChildrenByKind(TypeDoc.ReflectionKind.Method)
+    .reduce((a, v) => ({ ...a, [v.name]: v }), {});
+
+  describe('analyzeSignature()', () => {
+    const actuals = {};
+
+    it('expected and actual methods are equal', () => {
+      expect(Object.keys(methods).sort()).toEqual(Object.keys(expected).sort());
+    });
+
+    it.each(Object.keys(expected))('%s', (name) => {
+      const method = methods[name];
+      const actual = analyzeSignature(method.signatures[0], null, method.name);
+      actuals[name] = actual;
+
+      expect(prettyJson(actual)).toBe(prettyJson(expected[name]));
+    });
+
+    afterAll(() => {
+      // Write to file for easier comparison
+      writeFileSync(
+        resolve('test', 'scripts', 'apidoc', 'signature.actuals.json'),
+        prettyJson(actuals)
+      );
+    });
+  });
+});

test/scripts/apidoc/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "include": ["signature.example.ts"]
+}