Merge branch 'next' into docs/contributing

.gitignore

@@ -77,7 +77,6 @@ versions.json
 /dist
 /docs/.vitepress/cache
 /docs/.vitepress/dist
-/docs/api/typedoc.json
 /docs/public/api-diff-index.json
 /lib
 

scripts/apidocs/output/page.ts

@@ -3,7 +3,7 @@ import { resolve } from 'node:path';
 import type { ApiDocsMethod } from '../../../docs/.vitepress/components/api-docs/method';
 import type { RawApiDocsPage } from '../processing/class';
 import type { RawApiDocsMethod } from '../processing/method';
-import { formatMarkdown } from '../utils/format';
+import { formatMarkdown, formatTypescript } from '../utils/format';
 import { adjustUrls, codeToHtml, mdToHtml } from '../utils/markdown';
 import { FILE_PATH_API_DOCS } from '../utils/paths';
 import { required } from '../utils/value-checks';
@@ -33,7 +33,7 @@ export async function writePages(pages: RawApiDocsPage[]): Promise<void> {
 async function writePage(page: RawApiDocsPage): Promise<void> {
   try {
     await writePageMarkdown(page);
-    writePageJsonData(page);
+    await writePageJsonData(page);
   } catch (error) {
     throw new Error(`Error writing page ${page.title}`, { cause: error });
   }
@@ -98,10 +98,12 @@ async function writePageMarkdown(page: RawApiDocsPage): Promise<void> {
  *
  * @param page The page to write.
  */
-function writePageJsonData(page: RawApiDocsPage): void {
+async function writePageJsonData(page: RawApiDocsPage): Promise<void> {
   const { camelTitle, methods } = page;
   const pageData: Record<string, ApiDocsMethod> = Object.fromEntries(
-    methods.map((method) => [method.name, toMethodData(method)])
+    await Promise.all(
+      methods.map(async (method) => [method.name, await toMethodData(method)])
+    )
   );
   const content = JSON.stringify(pageData, null, 2);
 
@@ -110,7 +112,7 @@ function writePageJsonData(page: RawApiDocsPage): void {
 
 const defaultCommentRegex = /\s+Defaults to `([^`]+)`\..*/;
 
-function toMethodData(method: RawApiDocsMethod): ApiDocsMethod {
+async function toMethodData(method: RawApiDocsMethod): Promise<ApiDocsMethod> {
   const { name, signatures, source } = method;
   const signatureData = required(signatures.at(-1), 'method signature');
   const {
@@ -125,6 +127,8 @@ function toMethodData(method: RawApiDocsMethod): ApiDocsMethod {
     seeAlsos,
   } = signatureData;
   const { filePath, line } = source;
+  let formattedSignature = await formatTypescript(signature);
+  formattedSignature = formattedSignature.trim();
 
   /* Target order, omitted to improve diff to old files
   return {
@@ -161,7 +165,7 @@ function toMethodData(method: RawApiDocsMethod): ApiDocsMethod {
     sourcePath: `${filePath}#L${line}`,
     throws: throws.length === 0 ? undefined : mdToHtml(throws.join('\n'), true),
     returns: returns.text,
-    examples: codeToHtml([signature, ...examples].join('\n')),
+    examples: codeToHtml([formattedSignature, ...examples].join('\n')),
     deprecated: mdToHtml(deprecated),
     seeAlsos: seeAlsos.map((seeAlso) => mdToHtml(seeAlso, true)),
   };

scripts/apidocs/utils/format.ts

@@ -3,7 +3,7 @@ import { format } from 'prettier';
 import prettierConfig from '../../../.prettierrc.js';
 
 /**
- * Formats markdown contents.
+ * Formats Markdown contents.
  *
  * @param text The text to format.
  */
@@ -12,7 +12,7 @@ export async function formatMarkdown(text: string): Promise<string> {
 }
 
 /**
- * Formats typedoc contents.
+ * Formats TypeScript contents.
  *
  * @param text The text to format.
  */

tsconfig.json

@@ -17,7 +17,7 @@
   "exclude": [
     "node_modules",
     "dist",
-    // required for the typedoc related tests on macOS #2280
+    // required for the signature related tests on macOS #2280
     "test/scripts/apidocs/temp"
   ]
 }