chore(deps): update doc-dependencies (#1110)

Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: ST-DDT <[email protected]>

6 files changed, 132 insertions, 70 deletions

diff --git a/package.json b/package.json
index aa7aeb90..7d911deb 100644
--- a/package.json
+++ b/package.json
@@ -127,8 +127,8 @@
     "simple-git-hooks": "~2.8.0",
     "standard-version": "~9.5.0",
     "tsx": "~3.6.0",
-    "typedoc": "~0.22.17",
-    "typedoc-plugin-missing-exports": "~0.22.6",
+    "typedoc": "~0.23.2",
+    "typedoc-plugin-missing-exports": "~0.23.0",
     "typescript": "~4.7.4",
     "validator": "~13.7.0",
     "vite": "~2.9.13",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 6fea3b3e..e81372b2 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -35,8 +35,8 @@ specifiers:
   simple-git-hooks: ~2.8.0
   standard-version: ~9.5.0
   tsx: ~3.6.0
-  typedoc: ~0.22.17
-  typedoc-plugin-missing-exports: ~0.22.6
+  typedoc: ~0.23.2
+  typedoc-plugin-missing-exports: ~0.23.0
   typescript: ~4.7.4
   validator: ~13.7.0
   vite: ~2.9.13
@@ -78,8 +78,8 @@ devDependencies:
   simple-git-hooks: 2.8.0
   standard-version: 9.5.0
   tsx: 3.6.0
-  typedoc: [email protected]
-  typedoc-plugin-missing-exports: [email protected]
+  typedoc: [email protected]
+  typedoc-plugin-missing-exports: [email protected]
   typescript: 4.7.4
   validator: 13.7.0
   vite: 2.9.13
@@ -4380,22 +4380,21 @@ packages:
     resolution: {integrity: sha512-/aCDEGatGvZ2BIk+HmLf4ifCJFwvKFNb9/JeZPMulfgFracn9QFcAf5GO8B/mweUjSoblS5In0cWhqpfs/5PQA==}
     dev: true
 
-  /typedoc-plugin-missing-exports/[email protected]:
-    resolution: {integrity: sha512-1uguGQqa+c5f33nWS3v1mm0uAx4Ii1lw4Kx2zQksmYFKNEWTmrmMXbMNBoBg4wu0p4dFCNC7JIWPoRzpNS6pFA==}
+  /typedoc-plugin-missing-exports/[email protected]:
+    resolution: {integrity: sha512-9smahDSsFRno9ZwoEshQDuIYMHWGB1E6LUud5qMxR2wNZ0T4DlZz0QjoK3HzXtX34mUpTH0dYtt7NQUK4D6B6Q==}
     peerDependencies:
-      typedoc: 0.22.x
+      typedoc: 0.22.x || 0.23.x
     dependencies:
-      typedoc: [email protected]
+      typedoc: [email protected]
     dev: true
 
-  /typedoc/[email protected]:
-    resolution: {integrity: sha512-h6+uXHVVCPDaANzjwzdsj9aePBjZiBTpiMpBBeyh1zcN2odVsDCNajz8zyKnixF93HJeGpl34j/70yoEE5BfNg==}
-    engines: {node: '>= 12.10.0'}
+  /typedoc/[email protected]:
+    resolution: {integrity: sha512-THpC4vtb3wu1yck6YHzEc4ck6W4lScf8TD0Rg7XAetDih8BzP+ErYO0/6DtdzYcZyKkDwEoujkMeWW7CffCbrQ==}
+    engines: {node: '>= 14.14'}
     hasBin: true
     peerDependencies:
-      typescript: 4.0.x || 4.1.x || 4.2.x || 4.3.x || 4.4.x || 4.5.x || 4.6.x || 4.7.x
+      typescript: 4.6.x || 4.7.x
     dependencies:
-      glob: 8.0.3
       lunr: 2.3.9
       marked: 4.0.17
       minimatch: 5.1.0
diff --git a/scripts/apidoc/parameterDefaults.ts b/scripts/apidoc/parameterDefaults.ts
index 5e10202c..243d7e45 100644
--- a/scripts/apidoc/parameterDefaults.ts
+++ b/scripts/apidoc/parameterDefaults.ts
@@ -4,20 +4,16 @@ import type {
   EventCallback,
   JSONOutput,
   ProjectReflection,
-  SignatureReflection,
-} from 'typedoc';
-import {
-  Reflection,
-  ReflectionKind,
   SerializerComponent,
-  TypeScript,
+  SignatureReflection,
 } from 'typedoc';
+import { Reflection, ReflectionKind, TypeScript } from 'typedoc';
 
 const reflectionKindFunctionOrMethod =
   ReflectionKind.Function | ReflectionKind.Method;
 
 interface ParameterDefaultsAware extends Reflection {
-  implementationDefaultParameters: string[];
+  implementationDefaultParameters: Array<string | undefined>;
 }
 
 /**
@@ -50,7 +46,9 @@ export const parameterDefaultReader: EventCallback = (
  * @param value The default value to clean.
  * @returns The cleaned default value.
  */
-function cleanParameterDefault(value?: string): string {
+function cleanParameterDefault(value: string): string;
+function cleanParameterDefault(value?: string): string | undefined;
+function cleanParameterDefault(value?: string): string | undefined {
   if (value == null) {
     return undefined;
   }
@@ -61,19 +59,21 @@ function cleanParameterDefault(value?: string): string {
 /**
  * Serializer that adds the `implementationDefaultParameters` to the JSON output.
  */
-export class DefaultParameterAwareSerializer extends SerializerComponent<Reflection> {
-  serializeGroup(instance: unknown): boolean {
-    return instance instanceof Reflection;
-  }
+export class DefaultParameterAwareSerializer
+  implements SerializerComponent<Reflection>
+{
+  readonly priority = 0;
 
-  supports(): boolean {
-    return true;
+  supports(item: unknown): item is Reflection {
+    return item instanceof Reflection;
   }
 
-  toObject(item: Reflection, obj?: object): Partial<JSONOutput.Reflection> {
-    (obj as ParameterDefaultsAware).implementationDefaultParameters = (
-      item as ParameterDefaultsAware
-    ).implementationDefaultParameters;
+  toObject(
+    item: Reflection,
+    obj: Partial<JSONOutput.Reflection>
+  ): Partial<JSONOutput.Reflection> {
+    (obj as unknown as ParameterDefaultsAware).implementationDefaultParameters =
+      (item as ParameterDefaultsAware).implementationDefaultParameters;
     return obj;
   }
 }
@@ -101,10 +101,10 @@ export function patchProjectParameterDefaults(
  */
 function patchMethodParameterDefaults(method: DeclarationReflection): void {
   const signatures = method.signatures;
-  const signature = signatures[signatures.length - 1];
+  const signature = signatures?.[signatures.length - 1];
   const parameterDefaults = (method as unknown as ParameterDefaultsAware)
     .implementationDefaultParameters;
-  if (parameterDefaults) {
+  if (signature && parameterDefaults) {
     patchSignatureParameterDefaults(signature, parameterDefaults);
   }
 }
@@ -117,9 +117,10 @@ function patchMethodParameterDefaults(method: DeclarationReflection): void {
  */
 function patchSignatureParameterDefaults(
   signature: SignatureReflection,
-  parameterDefaults: string[]
+  parameterDefaults: Array<string | undefined>
 ): void {
-  const signatureParameters = signature.parameters;
+  const signatureParameters =
+    signature.parameters ?? Array.from({ length: parameterDefaults.length });
   if (signatureParameters.length !== parameterDefaults.length) {
     throw new Error('Unexpected parameter length mismatch');
   }
diff --git a/scripts/apidoc/signature.ts b/scripts/apidoc/signature.ts
index 154d1c72..0cae84a4 100644
--- a/scripts/apidoc/signature.ts
+++ b/scripts/apidoc/signature.ts
@@ -16,7 +16,14 @@ import type {
 } from '../../docs/.vitepress/components/api-docs/method';
 import vitepressConfig from '../../docs/.vitepress/config';
 import { faker } from '../../src';
-import { formatTypescript, pathOutputDir } from './utils';
+import {
+  extractRawExamples,
+  extractTagContent,
+  formatTypescript,
+  isDeprecated,
+  joinTagParts,
+  pathOutputDir,
+} from './utils';
 
 export function prettifyMethodName(method: string): string {
   return (
@@ -27,10 +34,7 @@ export function prettifyMethodName(method: string): string {
 }
 
 export function toBlock(comment?: Comment): string {
-  return (
-    (comment?.shortText.trim() || 'Missing') +
-    (comment?.text ? `\n\n${comment.text}` : '')
-  );
+  return joinTagParts(comment?.summary) || 'Missing';
 }
 
 const markdown = createMarkdownRenderer(
@@ -107,9 +111,9 @@ export function analyzeSignature(
 
   let examples: string;
   if (moduleName) {
-    examples = `faker.${moduleName}.${methodName}${signatureTypeParametersString}(${signatureParametersString}): ${signature.type.toString()}\n`;
+    examples = `faker.${moduleName}.${methodName}${signatureTypeParametersString}(${signatureParametersString}): ${signature.type?.toString()}\n`;
   } else {
-    examples = `faker.${methodName}${signatureTypeParametersString}(${signatureParametersString}): ${signature.type.toString()}\n`;
+    examples = `faker.${methodName}${signatureTypeParametersString}(${signatureParametersString}): ${signature.type?.toString()}\n`;
   }
   faker.seed(0);
   if (moduleName) {
@@ -125,19 +129,13 @@ export function analyzeSignature(
       // Ignore the error => hide the example call + result.
     }
   }
-  const exampleTags =
-    signature?.comment?.tags
-      .filter((tag) => tag.tagName === 'example')
-      .map((tag) => tag.text.trimEnd()) || [];
 
+  const exampleTags = extractRawExamples(signature);
   if (exampleTags.length > 0) {
     examples += `${exampleTags.join('\n').trim()}\n`;
   }
 
-  const seeAlsos =
-    signature.comment?.tags
-      .filter((t) => t.tagName === 'see')
-      .map((t) => t.text.trim()) ?? [];
+  const seeAlsos = extractTagContent('@see', signature);
 
   const prettyMethodName = prettifyMethodName(methodName);
   const code = '```';
@@ -149,7 +147,7 @@ export function analyzeSignature(
     parameters: parameters,
     returns: typeToText(signature.type),
     examples: mdToHtml(`${code}ts\n${examples}${code}`),
-    deprecated: signature.comment?.hasTag('deprecated') ?? false,
+    deprecated: isDeprecated(signature),
     seeAlsos,
   };
 }
@@ -189,8 +187,11 @@ function analyzeParameter(parameter: ParameterReflection): {
 
 function analyzeParameterOptions(
   name: string,
-  parameterType: SomeType
+  parameterType?: SomeType
 ): MethodParameter[] {
+  if (!parameterType) {
+    return [];
+  }
   if (parameterType.type === 'union') {
     return parameterType.types.flatMap((type) =>
       analyzeParameterOptions(name, type)
@@ -214,7 +215,10 @@ function isOptional(parameter: Reflection): boolean {
   return parameter.flags.hasFlag(ReflectionFlag.Optional);
 }
 
-function typeToText(type_: Type, short = false): string {
+function typeToText(type_?: Type, short = false): string {
+  if (!type_) {
+    return '?';
+  }
   const type = type_ as SomeType;
   switch (type.type) {
     case 'array':
@@ -257,7 +261,7 @@ function declarationTypeToText(
 ): string {
   switch (declaration.kind) {
     case ReflectionKind.Method:
-      return signatureTypeToText(declaration.signatures[0]);
+      return signatureTypeToText(declaration.signatures?.[0]);
 
     case ReflectionKind.Property:
       return typeToText(declaration.type);
@@ -285,9 +289,12 @@ function declarationTypeToText(
   }
 }
 
-function signatureTypeToText(signature: SignatureReflection): string {
+function signatureTypeToText(signature?: SignatureReflection): string {
+  if (!signature) {
+    return '(???) => ?';
+  }
   return `(${signature.parameters
-    .map((p) => `${p.name}: ${typeToText(p.type)}`)
+    ?.map((p) => `${p.name}: ${typeToText(p.type)}`)
     .join(', ')}) => ${typeToText(signature.type)}`;
 }
 
@@ -297,11 +304,12 @@ function signatureTypeToText(signature: SignatureReflection): string {
  * @param comment The comment to extract the default from.
  * @returns The extracted default value.
  */
-function extractDefaultFromComment(comment?: Comment): string {
+function extractDefaultFromComment(comment?: Comment): string | undefined {
   if (!comment) {
     return;
   }
-  const text = comment.shortText?.trim();
+  const summary = comment.summary;
+  const text = joinTagParts(summary).trim();
   if (!text) {
     return;
   }
@@ -312,6 +320,8 @@ function extractDefaultFromComment(comment?: Comment): string {
   if (result[3].trim()) {
     throw new Error(`Found description text after the default value:\n${text}`);
   }
-  comment.shortText = result[1];
+  summary.splice(summary.length - 2, 2);
+  const lastSummaryPart = summary[summary.length - 1];
+  lastSummaryPart.text = lastSummaryPart.text.replace(/[ \n]Defaults to $/, '');
   return result[2];
 }
diff --git a/scripts/apidoc/utils.ts b/scripts/apidoc/utils.ts
index 732c46a6..f4f0d3f7 100644
--- a/scripts/apidoc/utils.ts
+++ b/scripts/apidoc/utils.ts
@@ -1,6 +1,11 @@
 import { resolve } from 'node:path';
 import type { Options } from 'prettier';
 import { format } from 'prettier';
+import type {
+  CommentDisplayPart,
+  CommentTag,
+  SignatureReflection,
+} from 'typedoc';
 import * as TypeDoc from 'typedoc';
 import prettierConfig from '../../.prettierrc.cjs';
 import {
@@ -32,7 +37,7 @@ export function newTypeDocApp(): TypeDoc.Application {
     parameterDefaultReader
   );
   // Add to debug json output
-  app.serializer.addSerializer(new DefaultParameterAwareSerializer(undefined));
+  app.serializer.addSerializer(new DefaultParameterAwareSerializer());
 
   return app;
 }
@@ -75,3 +80,51 @@ const prettierTypescript: Options = {
   ...prettierConfig,
   parser: 'typescript',
 };
+
+/**
+ * Extracts the text (md) from a jsdoc tag.
+ *
+ * @param tag The tag to extract the text from.
+ * @param signature The signature to extract the text from.
+ */
+export function extractTagContent(
+  tag: `@${string}`,
+  signature?: SignatureReflection
+): string[] {
+  return signature?.comment?.getTags(tag).map(joinTagContent) ?? [];
+}
+
+/**
+ * Extracts the examples from the jsdocs without the surrounding md code block.
+ *
+ * @param signature The signature to extract the examples from.
+ */
+export function extractRawExamples(signature?: SignatureReflection): string[] {
+  return extractTagContent('@example', signature).map((tag) =>
+    tag.replace(/^```ts\n/, '').replace(/\n```$/, '')
+  );
+}
+
+/**
+ * Joins the parts of the given jsdocs tag.
+ */
+export function joinTagContent(tag: CommentTag): string {
+  return joinTagParts(tag?.content);
+}
+
+export function joinTagParts(parts: CommentDisplayPart[]): string;
+export function joinTagParts(parts?: CommentDisplayPart[]): string | undefined;
+export function joinTagParts(parts?: CommentDisplayPart[]): string | undefined {
+  return parts?.map((part) => part.text).join('');
+}
+
+/**
+ * Checks if the given signature is deprecated.
+ *
+ * @param signature The signature to check.
+ *
+ * @returns `true` if it is deprecated, otherwise `false`.
+ */
+export function isDeprecated(signature: SignatureReflection): boolean {
+  return extractTagContent('@deprecated', signature).length > 0;
+}
diff --git a/test/scripts/apidoc/examplesAndDeprecations.spec.ts b/test/scripts/apidoc/examplesAndDeprecations.spec.ts
index 87669d6b..314e72d4 100644
--- a/test/scripts/apidoc/examplesAndDeprecations.spec.ts
+++ b/test/scripts/apidoc/examplesAndDeprecations.spec.ts
@@ -4,6 +4,10 @@ import type { DeclarationReflection, SignatureReflection } from 'typedoc';
 import { ReflectionKind } from 'typedoc';
 import type { SpyInstance } from 'vitest';
 import { afterAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  extractRawExamples,
+  isDeprecated,
+} from '../../../scripts/apidoc/utils';
 import { faker } from '../../../src';
 import { loadProject } from './utils';
 
@@ -67,16 +71,11 @@ describe('examples and deprecations', () => {
     // eslint-disable-next-line @typescript-eslint/no-misused-promises
     it.each(Object.entries(methodsByName))('%s', async (methodName, method) => {
       const signatures: SignatureReflection[] =
-        method.signatures || method.type['declaration'].signatures;
+        method.signatures || method.type?.['declaration'].signatures;
       const signature = signatures[signatures.length - 1];
 
       // Extract examples and make them runnable
-      let examples =
-        signature?.comment?.tags
-          .filter((tag) => tag.tagName === 'example')
-          .map((tag) => tag.text.trimEnd())
-          .join('')
-          .trim() ?? '';
+      let examples = extractRawExamples(signature).join('').trim() ?? '';
       examples = examples.replace(
         /faker([A-Z]{2})\./g,
         (_, locale: string) => `faker.locale = '${locales[locale]}';\nfaker.`
@@ -99,7 +98,7 @@ describe('examples and deprecations', () => {
       await import(path);
 
       // Verify logging
-      const deprecatedFlag = signature.comment?.hasTag('deprecated') ?? false;
+      const deprecatedFlag = isDeprecated(signature);
       if (deprecatedFlag) {
         expect(consoleSpies[1]).toHaveBeenCalled();
       } else {