test(docs): ensure defaults are consistent

scripts/apidoc/parameterDefaults.ts

@@ -54,7 +54,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';
 
@@ -110,8 +110,7 @@ function analyzeParameter(parameter: ParameterReflection): {
   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) {
@@ -300,38 +299,39 @@ function signatureTypeToText(signature?: SignatureReflection): string {
 }
 
 /**
- * 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(summary.length - 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

@@ -238,6 +238,48 @@ 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(summary.length - 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/commerce/index.ts

@@ -141,9 +141,29 @@ export class CommerceModule {
     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,

src/modules/datatype/index.ts

@@ -28,7 +28,7 @@ export class DatatypeModule {
    * 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`.
@@ -298,7 +298,7 @@ export class DatatypeModule {
    * 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

@@ -515,7 +515,7 @@ export class DateModule {
    * @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' })

src/modules/finance/index.ts

@@ -386,7 +386,7 @@ export class FinanceModule {
    * @param max The upper bound for the amount. Defaults to `1000`.
    * @param dec The number of decimal places for the amount. Defaults to `2`.
    * @param symbol The symbol used to prefix the amount. Defaults to `''`.
-   * @param autoFormat If true this method will use `Number.toLocaleString()`. Otherwise it will use `Number.toFixed()`.
+   * @param autoFormat If true this method will use `Number.toLocaleString()`. Otherwise it will use `Number.toFixed()`. Defaults to `false`.
    *
    * @example
    * faker.finance.amount() // '617.87'
@@ -412,7 +412,7 @@ export class FinanceModule {
    * @param options.max The upper bound for the amount. Defaults to `1000`.
    * @param options.dec The number of decimal places for the amount. Defaults to `2`.
    * @param options.symbol The symbol used to prefix the amount. Defaults to `''`.
-   * @param options.autoFormat If true this method will use `Number.toLocaleString()`. Otherwise it will use `Number.toFixed()`.
+   * @param options.autoFormat If true this method will use `Number.toLocaleString()`. Otherwise it will use `Number.toFixed()`. Defaults to `false`.
    *
    * @example
    * faker.finance.amount() // '617.87'
@@ -463,11 +463,11 @@ export class FinanceModule {
    * @param options.max The upper bound for the amount. Defaults to `1000`.
    * @param options.dec The number of decimal places for the amount. Defaults to `2`.
    * @param options.symbol The symbol used to prefix the amount. Defaults to `''`.
-   * @param options.autoFormat If true this method will use `Number.toLocaleString()`. Otherwise it will use `Number.toFixed()`.
+   * @param options.autoFormat If true this method will use `Number.toLocaleString()`. Otherwise it will use `Number.toFixed()`. Defaults to `false`.
    * @param legacyMax The upper bound for the amount. Defaults to `1000`.
    * @param legacyDec The number of decimal places for the amount. Defaults to `2`.
    * @param legacySymbol The symbol used to prefix the amount. Defaults to `''`.
-   * @param legacyAutoFormat If true this method will use `Number.toLocaleString()`. Otherwise it will use `Number.toFixed()`.
+   * @param legacyAutoFormat If true this method will use `Number.toLocaleString()`. Otherwise it will use `Number.toFixed()`. Defaults to `false`.
    *
    * @example
    * faker.finance.amount() // '617.87'
@@ -530,11 +530,11 @@ export class FinanceModule {
    * @param options.max The upper bound for the amount. Defaults to `1000`.
    * @param options.dec The number of decimal places for the amount. Defaults to `2`.
    * @param options.symbol The symbol used to prefix the amount. Defaults to `''`.
-   * @param options.autoFormat If true this method will use `Number.toLocaleString()`. Otherwise it will use `Number.toFixed()`.
+   * @param options.autoFormat If true this method will use `Number.toLocaleString()`. Otherwise it will use `Number.toFixed()`. Defaults to `false`.
    * @param legacyMax The upper bound for the amount. Defaults to `1000`.
    * @param legacyDec The number of decimal places for the amount. Defaults to `2`.
    * @param legacySymbol The symbol used to prefix the amount. Defaults to `''`.
-   * @param legacyAutoFormat If true this method will use `Number.toLocaleString()`. Otherwise it will use `Number.toFixed()`.
+   * @param legacyAutoFormat If true this method will use `Number.toLocaleString()`. Otherwise it will use `Number.toFixed()`. Defaults to `false`.
    *
    * @example
    * faker.finance.amount() // '617.87'

src/modules/helpers/index.ts

@@ -109,7 +109,7 @@ export class HelpersModule {
    * For that all spaces (` `) are replaced by hyphens (`-`)
    * and most non word characters except for dots and hyphens will be removed.
    *
-   * @param string The input to slugify.
+   * @param string The input to slugify. Defaults to `''`.
    *
    * @example
    * faker.helpers.slugify() // ''
@@ -129,7 +129,7 @@ export class HelpersModule {
    * Parses the given string symbol by symbol and replaces the placeholders with digits (`0` - `9`).
    * `!` will be replaced by digits >=2 (`2` - `9`).
    *
-   * @param string The template string to parse.
+   * @param string The template string to parse. Defaults to `''`.
    * @param symbol The symbol to replace with digits. Defaults to `'#'`.
    *
    * @example
@@ -162,7 +162,7 @@ export class HelpersModule {
    * - `?` will be replaced with an upper letter ('A' - 'Z')
    * - and `*` will be replaced with either a digit or letter.
    *
-   * @param string The template string to parse.
+   * @param string The template string to parse. Defaults to `''`.
    *
    * @example
    * faker.helpers.replaceSymbols() // ''
@@ -227,8 +227,8 @@ export class HelpersModule {
    * This method supports both range patterns `[4-9]` as well as the patterns used by `replaceSymbolWithNumber()`.
    * `L` will be replaced with the appropriate Luhn checksum.
    *
-   * @param string The credit card format pattern. Defaults to `6453-####-####-####-###L`.
-   * @param symbol The symbol to replace with a digit.
+   * @param string The credit card format pattern. Defaults to `'6453-####-####-####-###L'`.
+   * @param symbol The symbol to replace with a digit. Defaults to `'#'`.
    *
    * @example
    * faker.helpers.replaceCreditCardSymbols() // '6453-4876-8626-8995-3771'
@@ -257,7 +257,7 @@ export class HelpersModule {
    * - `.{min,max}` => Repeat the character `min` to `max` times.
    * - `[min-max]` => Generate a number between min and max (inclusive).
    *
-   * @param string The template string to to parse.
+   * @param string The template string to to parse. Defaults to `''`.
    *
    * @example
    * faker.helpers.regexpStyleStringParse() // ''
@@ -1283,7 +1283,7 @@ export class HelpersModule {
    * @template TMethod The type of the method to execute.
    *
    * @param method The method used to generate the values.
-   * @param args The arguments used to call the method.
+   * @param args The arguments used to call the method. Defaults to `[]`.
    * @param options The optional options used to configure this method.
    * @param options.startTime This parameter does nothing.
    * @param options.maxTime The time in milliseconds this method may take before throwing an error. Defaults to `50`.

src/modules/location/index.ts

@@ -1081,8 +1081,22 @@ export class LocationModule {
    * @since 8.0.0
    */
   nearbyGPSCoordinate(options?: {
+    /**
+     * The original coordinate to get a new coordinate close to.
+     * If no coordinate is given, a random one will be chosen.
+     */
     origin?: [latitude: number, longitude: number];
+    /**
+     * The maximum distance from the given coordinate to the new coordinate.
+     *
+     * @default 10
+     */
     radius?: number;
+    /**
+     * If `true` assume the radius to be in kilometers. If `false` for miles.
+     *
+     * @default false
+     */
     isMetric?: boolean;
   }): [latitude: number, longitude: number];
   /**
@@ -1115,8 +1129,8 @@ export class LocationModule {
    * If no coordinate is given, a random one will be chosen.
    * @param options.radius The maximum distance from the given coordinate to the new coordinate. Defaults to `10`.
    * @param options.isMetric If `true` assume the radius to be in kilometers. If `false` for miles. Defaults to `false`.
-   * @param legacyRadius Deprecated, use `options.radius` instead.
-   * @param legacyIsMetric Deprecated, use `options.isMetric` instead.
+   * @param legacyRadius Deprecated, use `options.radius` instead. Defaults to `10`.
+   * @param legacyIsMetric Deprecated, use `options.isMetric` instead. Defaults to `false`.
    *
    * @example
    * faker.location.nearbyGPSCoordinate() // [ 33.8475, -170.5953 ]
@@ -1129,8 +1143,22 @@ export class LocationModule {
     options?:
       | [latitude: number, longitude: number]
       | {
+          /**
+           * The original coordinate to get a new coordinate close to.
+           * If no coordinate is given, a random one will be chosen.
+           */
           origin?: [latitude: number, longitude: number];
+          /**
+           * The maximum distance from the given coordinate to the new coordinate.
+           *
+           * @default 10
+           */
           radius?: number;
+          /**
+           * If `true` assume the radius to be in kilometers. If `false` for miles.
+           *
+           * @default false
+           */
           isMetric?: boolean;
         },
     legacyRadius?: number,

src/modules/random/index.ts

@@ -230,7 +230,7 @@ export class RandomModule {
   /**
    * Generating a string consisting of letters in the English alphabet.
    *
-   * @param options Either the number of characters or an options instance. Defaults to `{ count: 1, casing: 'mixed', bannedChars: [] }`.
+   * @param options Either the number of characters or an options instance.
    * @param options.count The number of characters to generate. Defaults to `1`.
    * @param options.casing The casing of the characters. Defaults to `'mixed'`.
    * @param options.bannedChars An array with characters to exclude. Defaults to `[]`.
@@ -291,7 +291,7 @@ export class RandomModule {
    * Generating a string consisting of alpha characters and digits.
    *
    * @param count The number of characters and digits to generate. Defaults to `1`.
-   * @param options The options to use. Defaults to `{ bannedChars: [] }`.
+   * @param options The options to use.
    * @param options.casing The casing of the characters. Defaults to `'lower'`.
    * @param options.bannedChars An array of characters and digits which should be banned in the generated string. Defaults to `[]`.
    *