test(docs): ensure defaults are consistent (#2177)

scripts/apidoc/parameter-defaults.ts

@@ -58,7 +58,7 @@ function cleanParameterDefault(value?: string): string | undefined {
   }
 
   // Strip type casts: "'foobar' as unknown as T" => "'foobar'"
-  return value.replace(/ as unknown as [A-Za-z<>]+/, '');
+  return value.replace(/( as unknown)? as [A-Za-z<>]+/, '');
 }
 
 /**

scripts/apidoc/signature.ts

@@ -23,8 +23,8 @@ import {
   extractSeeAlsos,
   extractSince,
   extractSourcePath,
+  extractSummaryDefault,
   extractThrows,
-  joinTagParts,
   toBlock,
 } from './typedoc';
 
@@ -108,8 +108,7 @@ async function analyzeParameter(parameter: ParameterReflection): Promise<{
   const name = parameter.name;
   const declarationName = name + (isOptional(parameter) ? '?' : '');
   const type = parameter.type;
-  const commentDefault = extractDefaultFromComment(parameter.comment);
-  const defaultValue = parameter.defaultValue ?? commentDefault;
+  const defaultValue = extractDefaultFromParameter(parameter);
 
   let signatureText = '';
   if (defaultValue) {
@@ -136,6 +135,7 @@ async function analyzeParameter(parameter: ParameterReflection): Promise<{
   };
 }
 
+// keep in sync with assertNestedParameterDefault
 async function analyzeParameterOptions(
   name: string,
   parameterType?: SomeType
@@ -311,39 +311,41 @@ async function signatureTypeToText(
 }
 
 /**
- * Extracts and removed the parameter default from the comments.
+ * Extracts and optionally removes the parameter default from the parameter.
+ *
+ * @param parameter The parameter to extract the default from.
+ * @param eraseDefault Whether to erase the default text from the parameter comment.
+ *
+ * @returns The extracted default value.
+ */
+function extractDefaultFromParameter(
+  parameter: ParameterReflection,
+  eraseDefault = true
+): string | undefined {
+  const commentDefault = extractDefaultFromComment(
+    parameter.comment,
+    eraseDefault
+  );
+  return parameter.defaultValue ?? commentDefault;
+}
+
+/**
+ * Extracts and optionally removes the parameter default from the comments.
  *
  * @param comment The comment to extract the default from.
+ * @param eraseDefault Whether to erase the default text from the comment.
  *
  * @returns The extracted default value.
  */
-function extractDefaultFromComment(comment?: Comment): string | undefined {
+function extractDefaultFromComment(
+  comment?: Comment,
+  eraseDefault = true
+): string | undefined {
   if (!comment) {
     return;
   }
 
-  const defaultTag = comment.getTag('@default');
-  if (defaultTag) {
-    return extractRawDefault({ comment });
-  }
-
-  const summary = comment.summary;
-  const text = joinTagParts(summary).trim();
-  if (!text) {
-    return;
-  }
-
-  const result = /^(.*)[ \n]Defaults to `([^`]+)`\.(.*)$/s.exec(text);
-  if (!result) {
-    return;
-  }
-
-  if (result[3].trim()) {
-    throw new Error(`Found description text after the default value:\n${text}`);
-  }
-
-  summary.splice(-2, 2);
-  const lastSummaryPart = summary[summary.length - 1];
-  lastSummaryPart.text = lastSummaryPart.text.replace(/[ \n]Defaults to $/, '');
-  return result[2];
+  const tagDefault = extractRawDefault({ comment });
+  const summaryDefault = extractSummaryDefault(comment, eraseDefault);
+  return tagDefault || summaryDefault;
 }

scripts/apidoc/typedoc.ts

@@ -246,6 +246,49 @@ export function extractRawDefault(reflection?: CommentHolder): string {
   return extractRawCode('@default', reflection)[0] ?? '';
 }
 
+/**
+ * Extracts and optionally removes the default from the comment summary.
+ *
+ * @param comment The comment to extract the default from.
+ * @param eraseDefault Whether to erase the default text from the comment.
+ *
+ * @returns The extracted default value.
+ */
+export function extractSummaryDefault(
+  comment?: Comment,
+  eraseDefault = true
+): string | undefined {
+  if (!comment) {
+    return;
+  }
+
+  const summary = comment.summary;
+  const text = joinTagParts(summary).trim();
+  if (!text) {
+    return;
+  }
+
+  const result = /^(.*)[ \n]Defaults to `([^`]+)`\.(.*)$/s.exec(text);
+  if (!result) {
+    return;
+  }
+
+  if (result[3].trim()) {
+    throw new Error(`Found description text after the default value:\n${text}`);
+  }
+
+  if (eraseDefault) {
+    summary.splice(-2, 2);
+    const lastSummaryPart = summary[summary.length - 1];
+    lastSummaryPart.text = lastSummaryPart.text.replace(
+      /[ \n]Defaults to $/,
+      ''
+    );
+  }
+
+  return result[2];
+}
+
 /**
  * Extracts the examples from the jsdocs without the surrounding md code block.
  *

src/modules/airline/index.ts

@@ -125,7 +125,7 @@ export class AirlineModule extends ModuleBase {
    * are used by airlines to identify reservations. They're also known as booking reference numbers,
    * locator codes, confirmation codes, or reservation codes.
    *
-   * @param options The options to use. Defaults to `{}`.
+   * @param options The options to use.
    * @param options.allowNumerics Whether to allow numeric characters. Defaults to `false`.
    * @param options.allowVisuallySimilarCharacters Whether to allow visually similar characters such as '1' and 'I'. Defaults to `false`.
    *
@@ -174,7 +174,7 @@ export class AirlineModule extends ModuleBase {
   /**
    * Generates a random seat.
    *
-   * @param options The options to use. Defaults to `{}`.
+   * @param options The options to use.
    * @param options.aircraftType The aircraft type. Can be one of `narrowbody`, `regional`, `widebody`. Defaults to `narrowbody`.
    *
    * @example
@@ -225,7 +225,7 @@ export class AirlineModule extends ModuleBase {
    * `${faker.airline.airline().iataCode}${faker.airline.flightNumber({ addLeadingZeros: true })}` // 'AA0798'
    * ```
    *
-   * @param options The options to use. Defaults to `{}`.
+   * @param options The options to use.
    * @param options.length The number or range of digits to generate. Defaults to `{ min: 1, max: 4 }`.
    * @param options.addLeadingZeros Whether to pad the flight number up to 4 digits with leading zeros. Defaults to `false`.
    *

src/modules/commerce/index.ts

@@ -115,7 +115,7 @@ export class CommerceModule extends ModuleBase {
   /**
    * Generates a price between min and max (inclusive).
    *
-   * @param options An options object. Defaults to `{}`.
+   * @param options An options object.
    * @param options.min The minimum price. Defaults to `1`.
    * @param options.max The maximum price. Defaults to `1000`.
    * @param options.dec The number of decimal places. Defaults to `2`.
@@ -179,7 +179,7 @@ export class CommerceModule extends ModuleBase {
   /**
    * Generates a price between min and max (inclusive).
    *
-   * @param options The minimum price or on options object. Defaults to `{}`.
+   * @param options The minimum price or on options object.
    * @param options.min The minimum price. Defaults to `1`.
    * @param options.max The maximum price. Defaults to `1000`.
    * @param options.dec The number of decimal places. Defaults to `2`.
@@ -201,9 +201,29 @@ export class CommerceModule extends ModuleBase {
     options?:
       | number
       | {
+          /**
+           * The minimum price.
+           *
+           * @default 1
+           */
           min?: number;
+          /**
+           * The maximum price.
+           *
+           * @default 1000
+           */
           max?: number;
+          /**
+           * The number of decimal places.
+           *
+           * @default 2
+           */
           dec?: number;
+          /**
+           * The currency value to use.
+           *
+           * @default ''
+           */
           symbol?: string;
         },
     legacyMax?: number,
@@ -213,7 +233,7 @@ export class CommerceModule extends ModuleBase {
   /**
    * Generates a price between min and max (inclusive).
    *
-   * @param options The minimum price or on options object. Defaults to `{}`.
+   * @param options The minimum price or on options object.
    * @param options.min The minimum price. Defaults to `1`.
    * @param options.max The maximum price. Defaults to `1000`.
    * @param options.dec The number of decimal places. Defaults to `2`.
@@ -330,7 +350,7 @@ export class CommerceModule extends ModuleBase {
   /**
    * Returns a random [ISBN](https://en.wikipedia.org/wiki/ISBN) identifier.
    *
-   * @param options The variant to return or an options object. Defaults to `{}`.
+   * @param options The variant to return or an options object.
    * @param options.variant The variant to return. Can be either `10` (10-digit format)
    * or `13` (13-digit format). Defaults to `13`.
    * @param options.separator The separator to use in the format. Defaults to `'-'`.

src/modules/datatype/index.ts

@@ -15,7 +15,7 @@ export class DatatypeModule extends SimpleModuleBase {
    * Returns a single random number between zero and the given max value or the given range with the specified precision.
    * The bounds are inclusive.
    *
-   * @param options Maximum value or options object.
+   * @param options Maximum value or options object. Defaults to `99999`.
    * @param options.min Lower bound for generated number. Defaults to `0`.
    * @param options.max Upper bound for generated number. Defaults to `min + 99999`.
    * @param options.precision Precision of the generated number. Defaults to `1`.
@@ -213,7 +213,7 @@ export class DatatypeModule extends SimpleModuleBase {
   /**
    * Returns a string containing UTF-16 chars between 33 and 125 (`!` to `}`).
    *
-   * @param options Length of the generated string or an options object. Defaults to `{}`.
+   * @param options Length of the generated string or an options object.
    * @param options.length Length of the generated string. Max length is `2^20`. Defaults to `10`.
    *
    * @see faker.string.sample()
@@ -285,7 +285,7 @@ export class DatatypeModule extends SimpleModuleBase {
    * If the probability is `>= 1.0`, it will always return `true`.
    * The probability is limited to two decimal places.
    *
-   * @param options The optional options object or the probability (`[0.00, 1.00]`) of returning `true`. Defaults to `0.5`.
+   * @param options The optional options object or the probability (`[0.00, 1.00]`) of returning `true`.
    * @param options.probability The probability (`[0.00, 1.00]`) of returning `true`. Defaults to `0.5`.
    *
    * @example

src/modules/date/index.ts

@@ -491,7 +491,7 @@ export class SimpleDateModule extends SimpleModuleBase {
    * @param options.to The late date boundary.
    * @param options.count The number of dates to generate. Defaults to `3`.
    * @param legacyTo Deprecated, use `options.to` instead.
-   * @param legacyCount Deprecated, use `options.count` instead.
+   * @param legacyCount Deprecated, use `options.count` instead. Defaults to `3`.
    *
    * @example
    * faker.date.betweens({ from: '2020-01-01T00:00:00.000Z', to: '2030-01-01T00:00:00.000Z' })