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

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

3 files changed, 49 insertions, 14 deletions

diff --git a/scripts/apidoc/apiDocsWriter.ts b/scripts/apidoc/apiDocsWriter.ts
index ba1e4367..c4fcd983 100644
--- a/scripts/apidoc/apiDocsWriter.ts
+++ b/scripts/apidoc/apiDocsWriter.ts
@@ -1,6 +1,7 @@
 import { writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import type { ProjectReflection } from 'typedoc';
+import { ReflectionKind } from 'typedoc';
 import type { Method } from '../../docs/.vitepress/components/api-docs/method';
 import type { APIGroup } from '../../docs/api/api-types';
 import { formatMarkdown, formatTypescript } from './format';
@@ -216,7 +217,9 @@ export function writeApiSearchIndex(pages: ModuleSummary[]): void {
  * @param project The typedoc project.
  */
 export function writeSourceBaseUrl(project: ProjectReflection): void {
-  const baseUrl = extractSourceBaseUrl(project);
+  const baseUrl = extractSourceBaseUrl(
+    project.getChildrenByKind(ReflectionKind.Class)[0]
+  );
 
   let content = `
   // This file is automatically generated.
diff --git a/scripts/apidoc/signature.ts b/scripts/apidoc/signature.ts
index 05944ba7..3d8fd6f7 100644
--- a/scripts/apidoc/signature.ts
+++ b/scripts/apidoc/signature.ts
@@ -20,11 +20,11 @@ import vitepressConfig from '../../docs/.vitepress/config';
 import { formatTypescript } from './format';
 import {
   extractDeprecated,
+  extractRawDefault,
   extractRawExamples,
   extractSeeAlsos,
   extractSince,
   extractSourcePath,
-  joinTagContent,
   joinTagParts,
 } from './typedoc';
 import { pathOutputDir } from './utils';
@@ -382,7 +382,7 @@ function extractDefaultFromComment(comment?: Comment): string | undefined {
 
   const defaultTag = comment.getTag('@default');
   if (defaultTag) {
-    return joinTagContent(defaultTag).join().trim();
+    return extractRawDefault({ comment });
   }
 
   const summary = comment.summary;
diff --git a/scripts/apidoc/typedoc.ts b/scripts/apidoc/typedoc.ts
index 0b19c1b4..7fc1450b 100644
--- a/scripts/apidoc/typedoc.ts
+++ b/scripts/apidoc/typedoc.ts
@@ -21,6 +21,8 @@ import {
 } from './parameterDefaults';
 import { mapByName } from './utils';
 
+type CommentHolder = Pick<Reflection, 'comment'>;
+
 /**
  * Loads the project using TypeDoc.
  *
@@ -152,7 +154,9 @@ export function extractModuleFieldName(module: DeclarationReflection): string {
  *
  * @param reflection The reflection instance to extract the source url from.
  */
-function extractSourceUrl(reflection: Reflection): string {
+function extractSourceUrl(
+  reflection: DeclarationReflection | SignatureReflection
+): string {
   const source = reflection.sources?.[0];
   return source?.url ?? '';
 }
@@ -162,7 +166,9 @@ function extractSourceUrl(reflection: Reflection): string {
  *
  * @param reflection The reflection instance to extract the source base url from.
  */
-export function extractSourceBaseUrl(reflection: Reflection): string {
+export function extractSourceBaseUrl(
+  reflection: DeclarationReflection | SignatureReflection
+): string {
   return extractSourceUrl(reflection).replace(
     /^(.*\/blob\/[0-9a-f]+\/)(.*)$/,
     '$1'
@@ -174,7 +180,9 @@ export function extractSourceBaseUrl(reflection: Reflection): string {
  *
  * @param reflection The reflection instance to extract the source path from.
  */
-export function extractSourcePath(reflection: Reflection): string {
+export function extractSourcePath(
+  reflection: DeclarationReflection | SignatureReflection
+): string {
   return extractSourceUrl(reflection).replace(
     /^(.*\/blob\/[0-9a-f]+\/)(.*)$/,
     '$2'
@@ -189,29 +197,51 @@ export function extractSourcePath(reflection: Reflection): string {
  */
 export function extractTagContent(
   tag: `@${string}`,
-  reflection?: Reflection,
+  reflection?: CommentHolder,
   tagProcessor: (tag: CommentTag) => string[] = joinTagContent
 ): string[] {
   return reflection?.comment?.getTags(tag).flatMap(tagProcessor) ?? [];
 }
 
 /**
- * Extracts the examples from the jsdocs without the surrounding md code block.
+ * Extracts the raw code from the jsdocs without the surrounding md code block.
  *
- * @param reflection The reflection to extract the examples from.
+ * @param tag The tag to extract the code from.
+ * @param reflection The reflection to extract the code from.
  */
-export function extractRawExamples(reflection?: Reflection): string[] {
-  return extractTagContent('@example', reflection).map((tag) =>
+function extractRawCode(
+  tag: `@${string}`,
+  reflection?: CommentHolder
+): string[] {
+  return extractTagContent(tag, reflection).map((tag) =>
     tag.replace(/^```ts\n/, '').replace(/\n```$/, '')
   );
 }
 
 /**
+ * Extracts the default from the jsdocs without the surrounding md code block.
+ *
+ * @param reflection The reflection to extract the examples from.
+ */
+export function extractRawDefault(reflection?: CommentHolder): string {
+  return extractRawCode('@default', reflection)[0] ?? '';
+}
+
+/**
+ * Extracts the examples from the jsdocs without the surrounding md code block.
+ *
+ * @param reflection The reflection to extract the examples from.
+ */
+export function extractRawExamples(reflection?: CommentHolder): string[] {
+  return extractRawCode('@example', reflection);
+}
+
+/**
  * Extracts all the `@see` references from the jsdocs separately.
  *
  * @param reflection The reflection to extract the see also references from.
  */
-export function extractSeeAlsos(reflection?: Reflection): string[] {
+export function extractSeeAlsos(reflection?: CommentHolder): string[] {
   return extractTagContent('@see', reflection, (tag) =>
     // If the @see tag contains code in backticks, the content is split into multiple parts.
     // So we join together, split on newlines and filter out empty tags.
@@ -249,7 +279,9 @@ export function joinTagParts(parts?: CommentDisplayPart[]): string | undefined {
  *
  * @returns The message explaining the deprecation if deprecated, otherwise `undefined`.
  */
-export function extractDeprecated(reflection?: Reflection): string | undefined {
+export function extractDeprecated(
+  reflection?: CommentHolder
+): string | undefined {
   const deprecated = extractTagContent('@deprecated', reflection).join().trim();
   return deprecated.length === 0 ? undefined : deprecated;
 }
@@ -261,6 +293,6 @@ export function extractDeprecated(reflection?: Reflection): string | undefined {
  *
  * @returns The contents of the `@since` tag.
  */
-export function extractSince(reflection: Reflection): string {
+export function extractSince(reflection: CommentHolder): string {
   return extractTagContent('@since', reflection).join().trim();
 }