docs: add jsdocs to the pre-built instances (#3193)

1 files changed, 63 insertions, 9 deletions

diff --git a/scripts/generate-locales.ts b/scripts/generate-locales.ts
index e18bdb71..13fe70fd 100644
--- a/scripts/generate-locales.ts
+++ b/scripts/generate-locales.ts
@@ -112,6 +112,21 @@ function escapeField(parent: string, module: string): string {
   return module;
 }
 
+async function loadMetadata(locale: string): Promise<MetadataDefinition> {
+  const imported = await import(
+    `file:${resolve(pathLocales, locale, 'metadata.ts')}`
+  );
+  return imported.default as MetadataDefinition;
+}
+
+async function tryLoadMetadata(locale: string): Promise<MetadataDefinition> {
+  try {
+    return await loadMetadata(locale);
+  } catch {
+    return {};
+  }
+}
+
 async function generateLocaleFile(locale: string): Promise<void> {
   const parts = locale.split('_');
   const locales = [locale];
@@ -135,14 +150,33 @@ async function generateLocaleFile(locale: string): Promise<void> {
     locales.push('base');
   }
 
-  let content = `
+  const metadata = await tryLoadMetadata(locale);
+
+  const imports = `import { Faker } from '../faker';
+${locales.map((imp) => `import ${imp} from '../locales/${imp}';`).join('\n')}`;
+
+  const jsdoc =
+    locale === 'base'
+      ? `The faker instance for the \`base\` locale.
+
+The base locale contains data that is shared across all locales such as ISO codes, time zones, and more.`
+      : `The faker instance for the \`${locale}\` locale.
+
+- Language: ${metadata.title}
+- Endonym: ${metadata.endonym}
+
+This instance uses the following locales internally (in descending precedence):
+
+${locales.map((locale) => `- \`${locale}\``).join('\n')}`;
+
+  const content = `
       ${autoGeneratedCommentHeader}
 
-      import { Faker } from '../faker';
-      ${locales
-        .map((imp) => `import ${imp} from '../locales/${imp}';`)
-        .join('\n')}
+      ${imports}
 
+      /**
+       * ${jsdoc.replaceAll('\n', '\n * ')}
+       */
       export const faker = new Faker({
         locale: ${
           locales.length === 1 ? locales[0] : `[${locales.join(', ')}]`
@@ -150,8 +184,10 @@ async function generateLocaleFile(locale: string): Promise<void> {
       });
       `;
 
-  content = await formatTypescript(content);
-  return writeFile(resolve(pathLocale, `${locale}.ts`), content);
+  return writeFile(
+    resolve(pathLocale, `${locale}.ts`),
+    await formatTypescript(content)
+  );
 }
 
 async function generateLocalesIndexFile(
@@ -166,6 +202,24 @@ async function generateLocalesIndexFile(
   modules = removeTsSuffix(modules);
   modules.sort();
 
+  const metadata = depth === 1 ? await tryLoadMetadata(name) : {};
+
+  const jsdoc =
+    depth === 1
+      ? name === 'base'
+        ? `/**
+ * The locale data for the \`base\` locale.
+ *
+ * The base locale contains data that is shared across all locales such as ISO codes, time zones, and more.
+ */`
+        : `/**
+ * The locale data for the \`${name}\` locale.
+ *
+ * - Language: ${metadata.title}
+ * - Endonym: ${metadata.endonym}
+ */`
+      : '';
+
   const content = [autoGeneratedCommentHeader];
   let fieldType = '';
   if (type !== 'any') {
@@ -182,6 +236,7 @@ async function generateLocalesIndexFile(
       (module) => `import ${escapeImport(name, module)} from './${module}';`
     ),
     '',
+    jsdoc,
     `const ${name}${fieldType} = {
         ${modules.map((module) => `${escapeField(name, module)},`).join('\n')}
       };`,
@@ -385,8 +440,7 @@ for (const locale of locales) {
   const pathMetadata = resolve(pathModules, 'metadata.ts');
   let localeTitle = 'No title found';
   try {
-    const metadataImport = await import(`file:${pathMetadata}`);
-    const metadata: MetadataDefinition = metadataImport.default;
+    const metadata: MetadataDefinition = await loadMetadata(locale);
     const { title } = metadata;
     if (!title) {
       throw new Error(`No title property found on ${JSON.stringify(metadata)}`);