docs: show examples for modules (#2406)

Co-authored-by: ST-DDT <ST-DDT@gmx.de>

scripts/apidoc/apiDocsWriter.ts

@@ -37,20 +37,23 @@ editLink: false
  * @param moduleName The name of the module to write the docs for.
  * @param lowerModuleName The lowercase name of the module.
  * @param comment The module comments.
+ * @param examples The example code.
  * @param deprecated The deprecation message.
  * @param methods The methods of the module.
  */
 export async function writeApiDocsModule(
   moduleName: string,
   lowerModuleName: string,
   comment: string,
+  examples: string | undefined,
   deprecated: string | undefined,
   methods: Method[]
 ): Promise<ModuleSummary> {
   await writeApiDocsModulePage(
     moduleName,
     lowerModuleName,
     comment,
+    examples,
     deprecated,
     methods
   );
@@ -83,12 +86,15 @@ export async function writeApiDocsModule(
  * @param moduleName The name of the module to write the docs for.
  * @param lowerModuleName The lowercase name of the module.
  * @param comment The module comments.
+ * @param examples The example code.
+ * @param deprecated The deprecation message.
  * @param methods The methods of the module.
  */
 async function writeApiDocsModulePage(
   moduleName: string,
   lowerModuleName: string,
   comment: string,
+  examples: string | undefined,
   deprecated: string | undefined,
   methods: Method[]
 ): Promise<void> {
@@ -118,6 +124,8 @@ async function writeApiDocsModulePage(
 
   ${comment}
 
+  ${examples == null ? '' : `<div class="examples">${examples}</div>`}
+
   :::
 
   ${methods

scripts/apidoc/fakerClass.ts

@@ -29,7 +29,7 @@ async function processClass(
 
   console.log(`Processing ${name} class`);
 
-  const { comment, deprecated } = analyzeModule(fakerClass);
+  const { comment, deprecated, examples } = analyzeModule(fakerClass);
   const methods: Method[] = [];
 
   console.debug(`- constructor`);
@@ -43,6 +43,7 @@ async function processClass(
     name,
     moduleFieldName,
     comment,
+    examples,
     deprecated,
     methods
   );

scripts/apidoc/fakerUtilities.ts

@@ -28,5 +28,12 @@ async function processUtilities(
     )
   );
 
-  return writeApiDocsModule('Utilities', 'utils', comment, undefined, methods);
+  return writeApiDocsModule(
+    'Utilities',
+    'utils',
+    comment,
+    undefined,
+    undefined,
+    methods
+  );
 }

scripts/apidoc/markdown.ts

@@ -45,6 +45,16 @@ function comparableSanitizedHtml(html: string): string {
     .replace(/'/g, "'");
 }
 
+/**
+ * Converts a Typescript code block to an HTML string and sanitizes it.
+ * @param code The code to convert.
+ * @returns The converted HTML string.
+ */
+export function codeToHtml(code: string): string {
+  const delimiter = '```';
+  return mdToHtml(`${delimiter}ts\n${code}\n${delimiter}`);
+}
+
 /**
  * Converts Markdown to an HTML string and sanitizes it.
  * @param md The markdown to convert.

scripts/apidoc/moduleMethods.ts

@@ -5,10 +5,12 @@ import type {
 } from 'typedoc';
 import type { Method } from '../../docs/.vitepress/components/api-docs/method';
 import { writeApiDocsModule } from './apiDocsWriter';
+import { codeToHtml } from './markdown';
 import { analyzeSignature } from './signature';
 import {
   extractDeprecated,
   extractDescription,
+  extractJoinedRawExamples,
   extractModuleFieldName,
   extractModuleName,
   selectApiMethodSignatures,
@@ -41,7 +43,7 @@ async function processModule(
   const moduleName = extractModuleName(module);
   console.log(`Processing Module ${moduleName}`);
   const moduleFieldName = extractModuleFieldName(module);
-  const { comment, deprecated } = analyzeModule(module);
+  const { comment, deprecated, examples } = analyzeModule(module);
   const methods = await processModuleMethods(
     module,
     `faker.${moduleFieldName}.`
@@ -51,6 +53,7 @@ async function processModule(
     moduleName,
     moduleFieldName,
     comment,
+    examples,
     deprecated,
     methods
   );
@@ -65,10 +68,15 @@ async function processModule(
 export function analyzeModule(module: DeclarationReflection): {
   comment: string;
   deprecated: string | undefined;
+  examples: string | undefined;
 } {
+  const examplesRaw = extractJoinedRawExamples(module);
+  const examples = examplesRaw ? codeToHtml(examplesRaw) : undefined;
+
   return {
     comment: adjustUrls(extractDescription(module)),
     deprecated: extractDeprecated(module),
+    examples,
   };
 }
 

scripts/apidoc/signature.ts

@@ -14,12 +14,12 @@ import type {
   MethodParameter,
 } from '../../docs/.vitepress/components/api-docs/method';
 import { formatTypescript } from './format';
-import { mdToHtml } from './markdown';
+import { codeToHtml, mdToHtml } from './markdown';
 import {
   extractDeprecated,
   extractDescription,
+  extractJoinedRawExamples,
   extractRawDefault,
-  extractRawExamples,
   extractSeeAlsos,
   extractSince,
   extractSourcePath,
@@ -28,8 +28,6 @@ import {
   toBlock,
 } from './typedoc';
 
-const code = '```';
-
 export async function analyzeSignature(
   signature: SignatureReflection,
   accessor: string,
@@ -74,9 +72,9 @@ export async function analyzeSignature(
 
   let examples = `${accessor}${methodName}${signatureTypeParametersString}(${signatureParametersString}): ${signature.type?.toString()}\n`;
 
-  const exampleTags = extractRawExamples(signature);
-  if (exampleTags.length > 0) {
-    examples += `${exampleTags.join('\n').trim()}\n`;
+  const exampleTags = extractJoinedRawExamples(signature);
+  if (exampleTags) {
+    examples += exampleTags;
   }
 
   const seeAlsos = extractSeeAlsos(signature).map((seeAlso) =>
@@ -97,7 +95,7 @@ export async function analyzeSignature(
     sourcePath: extractSourcePath(signature),
     throws,
     returns: await typeToText(signature.type),
-    examples: mdToHtml(`${code}ts\n${examples}${code}`),
+    examples: codeToHtml(examples),
     deprecated,
     seeAlsos,
   };

scripts/apidoc/typedoc.ts

@@ -244,10 +244,22 @@ export function extractRawDefault(reflection?: CommentHolder): string {
  *
  * @param reflection The reflection to extract the examples from.
  */
-export function extractRawExamples(reflection?: CommentHolder): string[] {
+function extractRawExamples(reflection?: CommentHolder): string[] {
   return extractRawCode('@example', reflection);
 }
 
+/**
+ * Extracts the examples from the jsdocs without the surrounding md code block, then joins them with newlines and trims.
+ *
+ * @param reflection The reflection to extract the examples from.
+ */
+export function extractJoinedRawExamples(
+  reflection?: CommentHolder
+): string | undefined {
+  const examples = extractRawExamples(reflection);
+  return examples.length === 0 ? undefined : examples.join('\n').trim();
+}
+
 /**
  * Extracts all the `@see` references from the jsdocs separately.
  *

test/scripts/apidoc/__snapshots__/module.spec.ts.snap

@@ -1,10 +1,20 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
+exports[`module > analyzeModule() > ModuleExampleTest 1`] = `
+{
+  "comment": "This is a description for a module with a code example",
+  "deprecated": undefined,
+  "examples": "<div class=\\"language-ts\\"><button title=\\"Copy Code\\" class=\\"copy\\"></button><span class=\\"lang\\">ts</span><pre v-pre class=\\"shiki material-theme-palenight\\"><code><span class=\\"line\\"><span style=\\"color:#89DDFF\\">new</span><span style=\\"color:#BABED8\\"> </span><span style=\\"color:#82AAFF\\">ModuleExampleTest</span><span style=\\"color:#BABED8\\">()</span></span></code></pre>
+</div>",
+}
+`;
+
 exports[`module > analyzeModule() > ModuleFakerJsLinkTest 1`] = `
 {
   "comment": "Description with a link to our [website](/)
 and [api docs](/api/).",
   "deprecated": undefined,
+  "examples": undefined,
 }
 `;
 
@@ -13,11 +23,13 @@ exports[`module > analyzeModule() > ModuleNextFakerJsLinkTest 1`] = `
   "comment": "Description with a link to our [website](/)
 and [api docs](/api/).",
   "deprecated": undefined,
+  "examples": undefined,
 }
 `;
 
 exports[`module > analyzeModule() > expected and actual modules are equal 1`] = `
 [
+  "ModuleExampleTest",
   "ModuleFakerJsLinkTest",
   "ModuleNextFakerJsLinkTest",
 ]

test/scripts/apidoc/module.example.ts

@@ -9,3 +9,11 @@ export class ModuleFakerJsLinkTest {}
  * and [api docs](https://next.fakerjs.dev/api/).
  */
 export class ModuleNextFakerJsLinkTest {}
+
+/**
+ * This is a description for a module with a code example
+ *
+ * @example
+ * new ModuleExampleTest()
+ */
+export class ModuleExampleTest {}

test/scripts/apidoc/verify-jsdoc-tags.spec.ts

@@ -7,8 +7,8 @@ import { analyzeSignature } from '../../../scripts/apidoc/signature';
 import {
   extractDeprecated,
   extractDescription,
+  extractJoinedRawExamples,
   extractModuleFieldName,
-  extractRawExamples,
   extractSeeAlsos,
   extractSince,
   extractTagContent,
@@ -110,7 +110,7 @@ describe('verify JSDoc tags', () => {
             // Write temp files to disk
 
             // Extract examples and make them runnable
-            const examples = extractRawExamples(signature).join('').trim();
+            const examples = extractJoinedRawExamples(signature);
 
             // Save examples to a file to run them later in the specific tests
             const dir = resolveDirToModule(moduleName);
@@ -135,7 +135,7 @@ describe('verify JSDoc tags', () => {
 
           it('verify @example tag', async () => {
             // Extract the examples
-            const examples = extractRawExamples(signature).join('').trim();
+            const examples = extractJoinedRawExamples(signature);
 
             expect(
               examples,