fix: jsdocs tests

Author: ST-DDT

src/utils/get-default-ref-date.ts

@@ -9,6 +9,27 @@ import type { FakerCore } from '../faker-core';
  *
  * @returns The newly created default reference date.
  *
+ * @example
+ * fakerCore.randomizer.seed(1234);
+ *
+ * // Default behavior
+ * // setDefaultRefDate(fakerCore);
+ * past(fakerCore); // Changes based on the current date/time
+ *
+ * // Use a static ref date
+ * setDefaultRefDate(fakerCore, new Date('2020-01-01'));
+ * past(fakerCore); // Reproducible '2019-07-03T08:27:58.118Z'
+ *
+ * // Use a ref date that changes every time it is used
+ * let clock = new Date("2020-01-01").getTime();
+ * setDefaultRefDate(fakerCore, () => {
+ *   clock += 1000; // +1s
+ *   return new Date(clock);
+ * });
+ *
+ * getDefaultRefDate(fakerCore) // 2020-01-01T00:00:01Z
+ * getDefaultRefDate(fakerCore) // 2020-01-01T00:00:02Z
+ *
  * @since 10.4.0
  */
 export function getDefaultRefDate(fakerCore: FakerCore): Date {

src/utils/resolve-locale-data.ts

@@ -30,7 +30,7 @@ type LocaleProxyEntry<T> = unknown extends T ? T : Readonly<NonNullable<T>>;
  * @throws {FakerError} If the category or entry is not defined in the locale data.
  *
  * @example
- * arrayElements(fakerCore, resolveLocaleData(fakerCore, 'date', 'weekday')); // 'Sunday'
+ * arrayElements(fakerCore, resolveLocaleData(fakerCore, 'animal', 'cat')); // 'Bengal'
  *
  * @since 10.4.0
  */

src/utils/set-default-ref-date.ts

@@ -12,7 +12,7 @@ import type { FakerCore } from '../faker-core';
  * @see faker.seed(): For generating reproducible values.
  *
  * @example
- * seed(fakerCore, 1234);
+ * fakerCore.randomizer.seed(1234);
  *
  * // Default behavior
  * // setDefaultRefDate(fakerCore);
@@ -29,8 +29,8 @@ import type { FakerCore } from '../faker-core';
  *   return new Date(clock);
  * });
  *
- * defaultRefDate(fakerCore) // 2020-01-01T00:00:01Z
- * defaultRefDate(fakerCore) // 2020-01-01T00:00:02Z
+ * getDefaultRefDate(fakerCore) // 2020-01-01T00:00:01Z
+ * getDefaultRefDate(fakerCore) // 2020-01-01T00:00:02Z
  *
  * @since 10.4.0
  */

test/scripts/apidocs/__snapshots__/verify-jsdoc-tags.spec.ts.snap

@@ -31,7 +31,10 @@ exports[`check docs completeness > all modules and methods are present 1`] = `
     [
       "generateMersenne32Randomizer",
       "generateMersenne53Randomizer",
+      "getDefaultRefDate",
       "mergeLocales",
+      "resolveLocaleData",
+      "setDefaultRefDate",
     ],
   ],
   [

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

@@ -24,6 +24,9 @@ afterAll(() => {
 });
 
 const modules = processComponents(getProject());
+const moduleByMethod = new Map(
+  modules.flatMap((m) => m.methods.map((method) => [method.name, m.camelTitle]))
+);
 
 function resolveDirToModule(moduleName: string): string {
   return resolve(tempDir, moduleName);
@@ -38,6 +41,13 @@ function resolvePathToMethodFile(
   return resolve(dir, `${methodName}_${signature}.ts`);
 }
 
+function toKebabCase(str: string): string {
+  return str
+    .replaceAll(/([a-z])([A-Z])/g, '$1-$2')
+    .replaceAll(/[\s_]+/g, '-')
+    .toLowerCase();
+}
+
 const allowedReferences = new Set(
   modules.flatMap(({ camelTitle, methods, category }) => {
     return methods.map(({ name }) =>
@@ -94,6 +104,10 @@ describe('verify JSDoc tags', () => {
         });
       });
 
+      const thisModuleByMethod = new Map(
+        module.methods.map((method) => [method.name, moduleName])
+      );
+
       describe.each(module.methods.map((m) => [m.name, m]))(
         '%s',
         (methodName, method) => {
@@ -145,10 +159,41 @@ ${examples}`;
                   ];
 
                   if (imports.length > 0) {
-                    examples = `import { ${imports.join(
-                      ', '
-                    )} } from '${relativeImportPath}';\n\n${examples}`;
+                    examples = `// imports
+import { ${imports.join(', ')} } from '${relativeImportPath}';
+
+${examples}`;
+                  }
+
+                  const functionImports = [
+                    ...new Set(examples.match(/\b(\w+)\(fakerCore/g)),
+                  ]
+                    .map((s) => s.replace('(fakerCore', ''))
+                    .map((functionName) => [
+                      functionName,
+                      (
+                        thisModuleByMethod.get(functionName) ??
+                        moduleByMethod.get(functionName) ??
+                        '..'
+                      )?.replace(
+                        'utils',
+                        moduleName === 'utils' ? '../utils' : 'utils'
+                      ),
+                    ]);
+
+                  if (examples.includes('fakerCore')) {
+                    examples = `// fakerCore
+import { base, en } from '${relativeImportPath}';
+import { createFakerCore } from '${relativeImportPath}/faker-core';
+const fakerCore = createFakerCore({ definitions: [en, base] });
+
+${examples.replace("import { fakerCore } from '../../../../../src';", '')}`;
                   }
+
+                  examples = `// functionImports
+${functionImports.map(([functionName, moduleName]) => `import { ${functionName} } from '${relativeImportPath}/modules/${moduleName}/${toKebabCase(functionName)}';`).join('\n')}
+
+${examples}`;
                 }
 
                 writeFileSync(path, examples);