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]>

3 files changed, 111 insertions, 47 deletions

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;
+}