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

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,23 +150,44 @@ 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(', ')}]`
         },
       });
       `;
 
-  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)}`);

src/locale/af_ZA.ts

@@ -8,6 +8,18 @@ import af_ZA from '../locales/af_ZA';
 import base from '../locales/base';
 import en from '../locales/en';
 
+/**
+ * The faker instance for the `af_ZA` locale.
+ *
+ * - Language: Afrikaans (South Africa)
+ * - Endonym: Afrikaans (Suid-Afrika)
+ *
+ * This instance uses the following locales internally (in descending precedence):
+ *
+ * - `af_ZA`
+ * - `en`
+ * - `base`
+ */
 export const faker = new Faker({
   locale: [af_ZA, en, base],
 });

src/locale/ar.ts

@@ -8,6 +8,18 @@ import ar from '../locales/ar';
 import base from '../locales/base';
 import en from '../locales/en';
 
+/**
+ * The faker instance for the `ar` locale.
+ *
+ * - Language: Arabic
+ * - Endonym: اَلْعَرَبِيَّةُ
+ *
+ * This instance uses the following locales internally (in descending precedence):
+ *
+ * - `ar`
+ * - `en`
+ * - `base`
+ */
 export const faker = new Faker({
   locale: [ar, en, base],
 });

src/locale/az.ts

@@ -8,6 +8,18 @@ import az from '../locales/az';
 import base from '../locales/base';
 import en from '../locales/en';
 
+/**
+ * The faker instance for the `az` locale.
+ *
+ * - Language: Azerbaijani
+ * - Endonym: azərbaycan dili
+ *
+ * This instance uses the following locales internally (in descending precedence):
+ *
+ * - `az`
+ * - `en`
+ * - `base`
+ */
 export const faker = new Faker({
   locale: [az, en, base],
 });

src/locale/base.ts

@@ -6,6 +6,11 @@
 import { Faker } from '../faker';
 import base from '../locales/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.
+ */
 export const faker = new Faker({
   locale: base,
 });

src/locale/cs_CZ.ts

@@ -8,6 +8,18 @@ import base from '../locales/base';
 import cs_CZ from '../locales/cs_CZ';
 import en from '../locales/en';
 
+/**
+ * The faker instance for the `cs_CZ` locale.
+ *
+ * - Language: Czech (Czechia)
+ * - Endonym: čeština (Česká republika)
+ *
+ * This instance uses the following locales internally (in descending precedence):
+ *
+ * - `cs_CZ`
+ * - `en`
+ * - `base`
+ */
 export const faker = new Faker({
   locale: [cs_CZ, en, base],
 });

src/locale/da.ts

@@ -8,6 +8,18 @@ import base from '../locales/base';
 import da from '../locales/da';
 import en from '../locales/en';
 
+/**
+ * The faker instance for the `da` locale.
+ *
+ * - Language: Danish
+ * - Endonym: Dansk
+ *
+ * This instance uses the following locales internally (in descending precedence):
+ *
+ * - `da`
+ * - `en`
+ * - `base`
+ */
 export const faker = new Faker({
   locale: [da, en, base],
 });

src/locale/de.ts

@@ -8,6 +8,18 @@ import base from '../locales/base';
 import de from '../locales/de';
 import en from '../locales/en';
 
+/**
+ * The faker instance for the `de` locale.
+ *
+ * - Language: German
+ * - Endonym: Deutsch
+ *
+ * This instance uses the following locales internally (in descending precedence):
+ *
+ * - `de`
+ * - `en`
+ * - `base`
+ */
 export const faker = new Faker({
   locale: [de, en, base],
 });

src/locale/de_AT.ts

@@ -9,6 +9,19 @@ import de from '../locales/de';
 import de_AT from '../locales/de_AT';
 import en from '../locales/en';
 
+/**
+ * The faker instance for the `de_AT` locale.
+ *
+ * - Language: German (Austria)
+ * - Endonym: Deutsch (Österreich)
+ *
+ * This instance uses the following locales internally (in descending precedence):
+ *
+ * - `de_AT`
+ * - `de`
+ * - `en`
+ * - `base`
+ */
 export const faker = new Faker({
   locale: [de_AT, de, en, base],
 });

src/locale/de_CH.ts

@@ -9,6 +9,19 @@ import de from '../locales/de';
 import de_CH from '../locales/de_CH';
 import en from '../locales/en';
 
+/**
+ * The faker instance for the `de_CH` locale.
+ *
+ * - Language: German (Switzerland)
+ * - Endonym: Deutsch (Schweiz)
+ *
+ * This instance uses the following locales internally (in descending precedence):
+ *
+ * - `de_CH`
+ * - `de`
+ * - `en`
+ * - `base`
+ */
 export const faker = new Faker({
   locale: [de_CH, de, en, base],
 });

src/locale/dv.ts

@@ -8,6 +8,18 @@ import base from '../locales/base';
 import dv from '../locales/dv';
 import en from '../locales/en';
 
+/**
+ * The faker instance for the `dv` locale.
+ *
+ * - Language: Maldivian
+ * - Endonym: ދިވެހި
+ *
+ * This instance uses the following locales internally (in descending precedence):
+ *
+ * - `dv`
+ * - `en`
+ * - `base`
+ */
 export const faker = new Faker({
   locale: [dv, en, base],
 });

src/locale/el.ts

@@ -8,6 +8,18 @@ import base from '../locales/base';
 import el from '../locales/el';
 import en from '../locales/en';
 
+/**
+ * The faker instance for the `el` locale.
+ *
+ * - Language: Greek
+ * - Endonym: Ελληνικά
+ *
+ * This instance uses the following locales internally (in descending precedence):
+ *
+ * - `el`
+ * - `en`
+ * - `base`
+ */
 export const faker = new Faker({
   locale: [el, en, base],
 });

src/locale/en.ts

@@ -7,6 +7,17 @@ import { Faker } from '../faker';
 import base from '../locales/base';
 import en from '../locales/en';
 
+/**
+ * The faker instance for the `en` locale.
+ *
+ * - Language: English
+ * - Endonym: English
+ *
+ * This instance uses the following locales internally (in descending precedence):
+ *
+ * - `en`
+ * - `base`
+ */
 export const faker = new Faker({
   locale: [en, base],
 });

src/locale/en_AU.ts

@@ -8,6 +8,18 @@ import base from '../locales/base';
 import en from '../locales/en';
 import en_AU from '../locales/en_AU';
 
+/**
+ * The faker instance for the `en_AU` locale.
+ *
+ * - Language: English (Australia)
+ * - Endonym: English (Australia)
+ *
+ * This instance uses the following locales internally (in descending precedence):
+ *
+ * - `en_AU`
+ * - `en`
+ * - `base`
+ */
 export const faker = new Faker({
   locale: [en_AU, en, base],
 });

src/locale/en_AU_ocker.ts

@@ -9,6 +9,19 @@ import en from '../locales/en';
 import en_AU from '../locales/en_AU';
 import en_AU_ocker from '../locales/en_AU_ocker';
 
+/**
+ * The faker instance for the `en_AU_ocker` locale.
+ *
+ * - Language: English (Australia Ocker)
+ * - Endonym: English (Australia)
+ *
+ * This instance uses the following locales internally (in descending precedence):
+ *
+ * - `en_AU_ocker`
+ * - `en_AU`
+ * - `en`
+ * - `base`
+ */
 export const faker = new Faker({
   locale: [en_AU_ocker, en_AU, en, base],
 });

src/locale/en_BORK.ts

@@ -8,6 +8,18 @@ import base from '../locales/base';
 import en from '../locales/en';
 import en_BORK from '../locales/en_BORK';
 
+/**
+ * The faker instance for the `en_BORK` locale.
+ *
+ * - Language: English (Bork)
+ * - Endonym: English (Bork)
+ *
+ * This instance uses the following locales internally (in descending precedence):
+ *
+ * - `en_BORK`
+ * - `en`
+ * - `base`
+ */
 export const faker = new Faker({
   locale: [en_BORK, en, base],
 });