docs: check api references (#2024)

6 files changed, 92 insertions, 87 deletions

diff --git a/scripts/apidoc.ts b/scripts/apidoc.ts
index ecb1f8fe..31171b9d 100644
--- a/scripts/apidoc.ts
+++ b/scripts/apidoc.ts
@@ -1,5 +1,5 @@
 import { generate } from './apidoc/generate';
-import { initMarkdownRenderer } from './apidoc/signature';
+import { initMarkdownRenderer } from './apidoc/markdown';
 
 async function build(): Promise<void> {
   await initMarkdownRenderer();
diff --git a/scripts/apidoc/fakerClass.ts b/scripts/apidoc/fakerClass.ts
index 9d11815f..c3a5287d 100644
--- a/scripts/apidoc/fakerClass.ts
+++ b/scripts/apidoc/fakerClass.ts
@@ -3,8 +3,8 @@ import { ReflectionKind } from 'typedoc';
 import type { Method } from '../../docs/.vitepress/components/api-docs/method';
 import { writeApiDocsModule } from './apiDocsWriter';
 import { processModuleMethods } from './moduleMethods';
-import { analyzeSignature, toBlock } from './signature';
-import { selectApiSignature } from './typedoc';
+import { analyzeSignature } from './signature';
+import { extractDescription, selectApiSignature } from './typedoc';
 import type { ModuleSummary } from './utils';
 
 export function processFakerClass(project: ProjectReflection): ModuleSummary {
@@ -21,7 +21,7 @@ export function processFakerClass(project: ProjectReflection): ModuleSummary {
 
 function processClass(fakerClass: DeclarationReflection): ModuleSummary {
   console.log(`Processing Faker class`);
-  const comment = toBlock(fakerClass.comment);
+  const comment = extractDescription(fakerClass);
   const methods: Method[] = [];
 
   console.debug(`- constructor`);
diff --git a/scripts/apidoc/markdown.ts b/scripts/apidoc/markdown.ts
new file mode 100644
index 00000000..8505b51d
--- /dev/null
+++ b/scripts/apidoc/markdown.ts
@@ -0,0 +1,68 @@
+import sanitizeHtml from 'sanitize-html';
+import type { MarkdownRenderer } from 'vitepress';
+import { createMarkdownRenderer } from 'vitepress';
+import vitepressConfig from '../../docs/.vitepress/config';
+import { pathOutputDir } from './utils';
+
+let markdown: MarkdownRenderer;
+
+export async function initMarkdownRenderer(): Promise<void> {
+  markdown = await createMarkdownRenderer(
+    pathOutputDir,
+    vitepressConfig.markdown,
+    '/'
+  );
+}
+
+const htmlSanitizeOptions: sanitizeHtml.IOptions = {
+  allowedTags: [
+    'a',
+    'button',
+    'code',
+    'div',
+    'li',
+    'p',
+    'pre',
+    'span',
+    'strong',
+    'ul',
+  ],
+  allowedAttributes: {
+    a: ['href', 'target', 'rel'],
+    button: ['class', 'title'],
+    div: ['class'],
+    pre: ['class', 'tabindex', 'v-pre'],
+    span: ['class', 'style'],
+  },
+  selfClosing: [],
+};
+
+function comparableSanitizedHtml(html: string): string {
+  return html
+    .replace(/&gt;/g, '>')
+    .replace(/ /g, '')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'");
+}
+
+/**
+ * Converts Markdown to an HTML string and sanitizes it.
+ * @param md The markdown to convert.
+ * @param inline Whether to render the markdown as inline, without a wrapping `<p>` tag. Defaults to `false`.
+ * @returns The converted HTML string.
+ */
+export function mdToHtml(md: string, inline: boolean = false): string {
+  const rawHtml = inline ? markdown.renderInline(md) : markdown.render(md);
+
+  const safeHtml: string = sanitizeHtml(rawHtml, htmlSanitizeOptions);
+  // Revert some escaped characters for comparison.
+  if (comparableSanitizedHtml(rawHtml) === comparableSanitizedHtml(safeHtml)) {
+    return safeHtml.replace(/https:\/\/(next.)?fakerjs.dev\//g, '/');
+  }
+
+  console.debug('Rejected unsafe md:', md);
+  console.error('Rejected unsafe html:', rawHtml);
+  console.error('Rejected unsafe html:', comparableSanitizedHtml(rawHtml));
+  console.error('Expected safe html:', comparableSanitizedHtml(safeHtml));
+  throw new Error('Found unsafe html');
+}
diff --git a/scripts/apidoc/moduleMethods.ts b/scripts/apidoc/moduleMethods.ts
index 9c902dd7..55b1869f 100644
--- a/scripts/apidoc/moduleMethods.ts
+++ b/scripts/apidoc/moduleMethods.ts
@@ -5,9 +5,10 @@ import type {
 } from 'typedoc';
 import type { Method } from '../../docs/.vitepress/components/api-docs/method';
 import { writeApiDocsModule } from './apiDocsWriter';
-import { analyzeSignature, stripAbsoluteFakerUrls, toBlock } from './signature';
+import { analyzeSignature } from './signature';
 import {
   extractDeprecated,
+  extractDescription,
   extractModuleFieldName,
   extractModuleName,
   selectApiMethodSignatures,
@@ -35,7 +36,7 @@ function processModule(module: DeclarationReflection): ModuleSummary {
   const moduleName = extractModuleName(module);
   const moduleFieldName = extractModuleFieldName(module);
   console.log(`Processing Module ${moduleName}`);
-  const comment = stripAbsoluteFakerUrls(toBlock(module.comment));
+  const comment = extractDescription(module);
   const deprecated = extractDeprecated(module);
   const methods = processModuleMethods(module, `faker.${moduleFieldName}.`);
 
diff --git a/scripts/apidoc/signature.ts b/scripts/apidoc/signature.ts
index 8b5083ae..67101574 100644
--- a/scripts/apidoc/signature.ts
+++ b/scripts/apidoc/signature.ts
@@ -1,4 +1,3 @@
-import sanitizeHtml from 'sanitize-html';
 import type {
   Comment,
   DeclarationReflection,
@@ -10,16 +9,15 @@ import type {
   Type,
 } from 'typedoc';
 import { ReflectionFlag, ReflectionKind } from 'typedoc';
-import type { MarkdownRenderer } from 'vitepress';
-import { createMarkdownRenderer } from 'vitepress';
 import type {
   Method,
   MethodParameter,
 } from '../../docs/.vitepress/components/api-docs/method';
-import vitepressConfig from '../../docs/.vitepress/config';
 import { formatTypescript } from './format';
+import { mdToHtml } from './markdown';
 import {
   extractDeprecated,
+  extractDescription,
   extractRawDefault,
   extractRawExamples,
   extractSeeAlsos,
@@ -27,84 +25,11 @@ import {
   extractSourcePath,
   extractThrows,
   joinTagParts,
+  toBlock,
 } from './typedoc';
-import { pathOutputDir } from './utils';
 
 const code = '```';
 
-export const MISSING_DESCRIPTION = 'Missing';
-
-export function toBlock(comment?: Comment): string {
-  return joinTagParts(comment?.summary) || MISSING_DESCRIPTION;
-}
-
-export function stripAbsoluteFakerUrls(markdown: string): string {
-  return markdown.replace(/https:\/\/(next.)?fakerjs.dev\//g, '/');
-}
-
-let markdown: MarkdownRenderer;
-
-export async function initMarkdownRenderer(): Promise<void> {
-  markdown = await createMarkdownRenderer(
-    pathOutputDir,
-    vitepressConfig.markdown,
-    '/'
-  );
-}
-
-const htmlSanitizeOptions: sanitizeHtml.IOptions = {
-  allowedTags: [
-    'a',
-    'button',
-    'code',
-    'div',
-    'li',
-    'p',
-    'pre',
-    'span',
-    'strong',
-    'ul',
-  ],
-  allowedAttributes: {
-    a: ['href', 'target', 'rel'],
-    button: ['class', 'title'],
-    div: ['class'],
-    pre: ['class', 'tabindex', 'v-pre'],
-    span: ['class', 'style'],
-  },
-  selfClosing: [],
-};
-
-function comparableSanitizedHtml(html: string): string {
-  return html
-    .replace(/&gt;/g, '>')
-    .replace(/ /g, '')
-    .replace(/&quot;/g, '"')
-    .replace(/&#39;/g, "'");
-}
-
-/**
- * Converts Markdown to an HTML string and sanitizes it.
- * @param md The markdown to convert.
- * @param inline Whether to render the markdown as inline, without a wrapping `<p>` tag. Defaults to `false`.
- * @returns The converted HTML string.
- */
-function mdToHtml(md: string, inline: boolean = false): string {
-  const rawHtml = inline ? markdown.renderInline(md) : markdown.render(md);
-
-  const safeHtml: string = sanitizeHtml(rawHtml, htmlSanitizeOptions);
-  // Revert some escaped characters for comparison.
-  if (comparableSanitizedHtml(rawHtml) === comparableSanitizedHtml(safeHtml)) {
-    return safeHtml;
-  }
-
-  console.debug('Rejected unsafe md:', md);
-  console.error('Rejected unsafe html:', rawHtml);
-  console.error('Rejected unsafe html:', comparableSanitizedHtml(rawHtml));
-  console.error('Expected safe html:', comparableSanitizedHtml(safeHtml));
-  throw new Error('Found unsafe html');
-}
-
 export function analyzeSignature(
   signature: SignatureReflection,
   accessor: string,
@@ -120,7 +45,7 @@ export function analyzeSignature(
     parameters.push({
       name: `<${parameter.name}>`,
       type: parameter.type ? typeToText(parameter.type) : undefined,
-      description: mdToHtml(toBlock(parameter.comment)),
+      description: mdToHtml(extractDescription(parameter)),
     });
   }
 
@@ -166,7 +91,7 @@ export function analyzeSignature(
 
   return {
     name: methodName,
-    description: mdToHtml(toBlock(signature.comment)),
+    description: mdToHtml(extractDescription(signature)),
     parameters: parameters,
     since: extractSince(signature),
     sourcePath: extractSourcePath(signature),
@@ -200,7 +125,7 @@ function analyzeParameter(parameter: ParameterReflection): {
       name: declarationName,
       type: typeToText(type, true),
       default: defaultValue,
-      description: mdToHtml(toBlock(parameter.comment)),
+      description: mdToHtml(extractDescription(parameter)),
     },
   ];
   parameters.push(...analyzeParameterOptions(name, type));
diff --git a/scripts/apidoc/typedoc.ts b/scripts/apidoc/typedoc.ts
index 858171ac..1a782aa9 100644
--- a/scripts/apidoc/typedoc.ts
+++ b/scripts/apidoc/typedoc.ts
@@ -1,4 +1,5 @@
 import type {
+  Comment,
   CommentDisplayPart,
   CommentTag,
   DeclarationReflection,
@@ -149,6 +150,16 @@ export function extractModuleFieldName(module: DeclarationReflection): string {
   return moduleName.substring(0, 1).toLowerCase() + moduleName.substring(1);
 }
 
+export const MISSING_DESCRIPTION = 'Missing';
+
+export function toBlock(comment?: Comment): string {
+  return joinTagParts(comment?.summary) || MISSING_DESCRIPTION;
+}
+
+export function extractDescription(reflection: Reflection): string {
+  return toBlock(reflection.comment);
+}
+
 /**
  * Extracts the source url from the jsdocs.
  *