docs: nice string literals

scripts/apidoc/apiDocsWriter.ts

@@ -1,11 +1,13 @@
 import { writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import type { Options } from 'prettier';
-import { format } from 'prettier';
-import prettierConfig from '../../.prettierrc.cjs';
 import type { Method } from '../../docs/.vitepress/components/api-docs/method';
 import type { PageIndex } from './utils';
-import { pathDocsDir, pathOutputDir } from './utils';
+import {
+  formatMarkdown,
+  formatTypescript,
+  pathDocsDir,
+  pathOutputDir,
+} from './utils';
 
 const pathDocsApiPages = resolve(pathDocsDir, '.vitepress', 'api-pages.ts');
 
@@ -18,21 +20,6 @@ editLink: false
 
 `;
 
-const prettierMarkdown: Options = {
-  ...prettierConfig,
-  parser: 'markdown',
-};
-
-const prettierTypescript: Options = {
-  ...prettierConfig,
-  parser: 'typescript',
-};
-
-const prettierBabel: Options = {
-  ...prettierConfig,
-  parser: 'babel',
-};
-
 /**
  * Writes the api page for the given module to the correct location.
  *
@@ -75,7 +62,7 @@ export function writeApiDocsModulePage(
   <ApiDocsMethod v-for="method of methods" :key="method.name" :method="method" v-once />
   `.replace(/\n +/g, '\n');
 
-  content = vitePressInFileOptions + format(content, prettierMarkdown);
+  content = vitePressInFileOptions + formatMarkdown(content);
 
   writeFileSync(resolve(pathOutputDir, lowerModuleName + '.md'), content);
 }
@@ -98,7 +85,7 @@ export function writeApiDocsDirectPage(methodName: string): void {
   <ApiDocsMethod v-for="method of methods" :key="method.name" :method="method" v-once />
   `.replace(/\n +/g, '\n');
 
-  content = vitePressInFileOptions + format(content, prettierMarkdown);
+  content = vitePressInFileOptions + formatMarkdown(content);
 
   writeFileSync(resolve(pathOutputDir, methodName + '.md'), content);
 }
@@ -122,7 +109,7 @@ export const ${lowerModuleName}: Method[] = ${JSON.stringify(
     2
   )}`;
 
-  contentTs = format(contentTs, prettierTypescript);
+  contentTs = formatTypescript(contentTs);
 
   writeFileSync(resolve(pathOutputDir, lowerModuleName + '.ts'), contentTs);
 }
@@ -142,7 +129,7 @@ export function writeApiPagesIndex(pages: PageIndex): void {
     export const apiPages = ${JSON.stringify(pages)};
     `.replace(/\n +/, '\n');
 
-  apiPagesContent = format(apiPagesContent, prettierBabel);
+  apiPagesContent = formatTypescript(apiPagesContent);
 
   writeFileSync(pathDocsApiPages, apiPagesContent);
 }

scripts/apidoc/signature.ts

@@ -15,7 +15,7 @@ import type {
   MethodParameter,
 } from '../../docs/.vitepress/components/api-docs/method';
 import { faker } from '../../src';
-import { pathOutputDir } from './utils';
+import { formatTypescript, pathOutputDir } from './utils';
 // TODO ST-DDT 2022-02-20: Actually import this/fix module import errors
 // import vitepressConfig from '../../docs/.vitepress/config';
 
@@ -245,6 +245,8 @@ function typeToText(type_: Type, short = false): string {
         type.indexType,
         short
       )}]`;
+    case 'literal':
+      return formatTypescript(type.toString()).replace(/;\n$/, '');
     default:
       return type.toString();
   }

scripts/apidoc/utils.ts

@@ -1,5 +1,8 @@
 import { resolve } from 'node:path';
+import type { Options } from 'prettier';
+import { format } from 'prettier';
 import * as TypeDoc from 'typedoc';
+import prettierConfig from '../../.prettierrc.cjs';
 import {
   DefaultParameterAwareSerializer,
   parameterDefaultReader,
@@ -44,3 +47,31 @@ export function newTypeDocApp(): TypeDoc.Application {
 export function patchProject(project: TypeDoc.ProjectReflection): void {
   patchProjectParameterDefaults(project);
 }
+
+/**
+ * Formats markdown contents.
+ *
+ * @param text The text to format.
+ */
+export function formatMarkdown(text: string): string {
+  return format(text, prettierMarkdown);
+}
+
+/**
+ * Formats typedoc contents.
+ *
+ * @param text The text to format.
+ */
+export function formatTypescript(text: string): string {
+  return format(text, prettierTypescript);
+}
+
+const prettierMarkdown: Options = {
+  ...prettierConfig,
+  parser: 'markdown',
+};
+
+const prettierTypescript: Options = {
+  ...prettierConfig,
+  parser: 'typescript',
+};

test/scripts/apidoc/signature.example.ts

@@ -115,6 +115,15 @@ export class SignatureTest {
     return fn('a');
   }
 
+  /**
+   * Test with string union.
+   *
+   * @param value `'a'` or `'b'`.
+   */
+  stringUnionParamMethod(value: 'a' | 'b'): string {
+    return value;
+  }
+
   /**
    * Test with LiteralUnion.
    *

test/scripts/apidoc/signature.expected.json

@@ -39,12 +39,12 @@
     "parameters": [
       {
         "name": "value",
-        "type": "\"a\" | \"b\" | string",
+        "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>",
+    "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": []
   },
@@ -272,5 +272,21 @@
     "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": []
+  },
+  "stringUnionParamMethod": {
+    "name": "stringUnionParamMethod",
+    "title": "String Union Param Method",
+    "description": "<p>Test with string union.</p>\n",
+    "parameters": [
+      {
+        "name": "value",
+        "type": "'a' | 'b'",
+        "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\">stringUnionParamMethod</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 punctuation\">)</span><span class=\"token operator\">:</span> <span class=\"token builtin\">string</span>\n</code></pre>\n</div>",
+    "deprecated": false,
+    "seeAlsos": []
   }
 }