docs(string): improve documentation for length parameters (#3216)

Author: ST-DDT

src/modules/string/index.ts

@@ -103,7 +103,7 @@ export class StringModule extends SimpleModuleBase {
    *
    * @param characters The characters to use for the string. Can be a string or an array of characters.
    * If it is an array, then each element is treated as a single character even if it is a string with multiple characters.
-   * @param length The length of the string to generate. Defaults to `1`.
+   * @param length The length of the string to generate either as a fixed length or as a length range. Defaults to `1`.
    * @param length.min The minimum length of the string to generate.
    * @param length.max The maximum length of the string to generate.
    *
@@ -155,8 +155,8 @@ export class StringModule extends SimpleModuleBase {
   /**
    * Generating a string consisting of letters in the English alphabet.
    *
-   * @param options Either the number of characters or an options instance.
-   * @param options.length The number or range of characters to generate. Defaults to `1`.
+   * @param options Either the length of the string to generate or the optional options object.
+   * @param options.length The length of the string to generate either as a fixed length or as a length range. Defaults to `1`.
    * @param options.casing The casing of the characters. Defaults to `'mixed'`.
    * @param options.exclude An array with characters which should be excluded in the generated string. Defaults to `[]`.
    *
@@ -175,19 +175,19 @@ export class StringModule extends SimpleModuleBase {
       | number
       | {
           /**
-           * The number or range of characters to generate.
+           * The length of the string to generate either as a fixed length or as a length range.
            *
            * @default 1
            */
           length?:
             | number
             | {
                 /**
-                 * The minimum number of characters to generate.
+                 * The minimum length of the string to generate.
                  */
                 min: number;
                 /**
-                 * The maximum number of characters to generate.
+                 * The maximum length of the string to generate.
                  */
                 max: number;
               };
@@ -249,8 +249,8 @@ export class StringModule extends SimpleModuleBase {
   /**
    * Generating a string consisting of alpha characters and digits.
    *
-   * @param options Either the number of characters or an options instance.
-   * @param options.length The number or range of characters and digits to generate. Defaults to `1`.
+   * @param options Either the length of the string to generate or the optional options object.
+   * @param options.length The length of the string to generate either as a fixed length or as a length range. Defaults to `1`.
    * @param options.casing The casing of the characters. Defaults to `'mixed'`.
    * @param options.exclude An array of characters and digits which should be excluded in the generated string. Defaults to `[]`.
    *
@@ -269,19 +269,19 @@ export class StringModule extends SimpleModuleBase {
       | number
       | {
           /**
-           * The number or range of characters and digits to generate.
+           * The length of the string to generate either as a fixed length or as a length range.
            *
            * @default 1
            */
           length?:
             | number
             | {
                 /**
-                 * The minimum number of characters and digits to generate.
+                 * The minimum length of the string to generate.
                  */
                 min: number;
                 /**
-                 * The maximum number of characters and digits to generate.
+                 * The maximum length of the string to generate.
                  */
                 max: number;
               };
@@ -345,7 +345,7 @@ export class StringModule extends SimpleModuleBase {
    * Returns a [binary](https://en.wikipedia.org/wiki/Binary_number) string.
    *
    * @param options The optional options object.
-   * @param options.length The number or range of characters to generate after the prefix. Defaults to `1`.
+   * @param options.length The length of the string (excluding the prefix) to generate either as a fixed length or as a length range. Defaults to `1`.
    * @param options.prefix Prefix for the generated number. Defaults to `'0b'`.
    *
    * @see faker.number.binary(): For generating a binary number (within a range).
@@ -362,19 +362,19 @@ export class StringModule extends SimpleModuleBase {
   binary(
     options: {
       /**
-       * The number or range of characters to generate after the prefix.
+       * The length of the string (excluding the prefix) to generate either as a fixed length or as a length range.
        *
        * @default 1
        */
       length?:
         | number
         | {
             /**
-             * The minimum number of characters to generate.
+             * The minimum length of the string (excluding the prefix) to generate.
              */
             min: number;
             /**
-             * The maximum number of characters to generate.
+             * The maximum length of the string (excluding the prefix) to generate.
              */
             max: number;
           };
@@ -397,7 +397,7 @@ export class StringModule extends SimpleModuleBase {
    * Returns an [octal](https://en.wikipedia.org/wiki/Octal) string.
    *
    * @param options The optional options object.
-   * @param options.length The number or range of characters to generate after the prefix. Defaults to `1`.
+   * @param options.length The length of the string (excluding the prefix) to generate either as a fixed length or as a length range. Defaults to `1`.
    * @param options.prefix Prefix for the generated number. Defaults to `'0o'`.
    *
    * @see faker.number.octal(): For generating an octal number (within a range).
@@ -414,19 +414,19 @@ export class StringModule extends SimpleModuleBase {
   octal(
     options: {
       /**
-       * The number or range of characters to generate after the prefix.
+       * The length of the string (excluding the prefix) to generate either as a fixed length or as a length range.
        *
        * @default 1
        */
       length?:
         | number
         | {
             /**
-             * The minimum number of characters to generate.
+             * The minimum length of the string (excluding the prefix) to generate.
              */
             min: number;
             /**
-             * The maximum number of characters to generate.
+             * The maximum length of the string (excluding the prefix) to generate.
              */
             max: number;
           };
@@ -452,7 +452,7 @@ export class StringModule extends SimpleModuleBase {
    * Returns a [hexadecimal](https://en.wikipedia.org/wiki/Hexadecimal) string.
    *
    * @param options The optional options object.
-   * @param options.length The number or range of characters to generate after the prefix. Defaults to `1`.
+   * @param options.length The length of the string (excluding the prefix) to generate either as a fixed length or as a length range. Defaults to `1`.
    * @param options.casing Casing of the generated number. Defaults to `'mixed'`.
    * @param options.prefix Prefix for the generated number. Defaults to `'0x'`.
    *
@@ -472,19 +472,19 @@ export class StringModule extends SimpleModuleBase {
   hexadecimal(
     options: {
       /**
-       * The number or range of characters to generate after the prefix.
+       * The length of the string (excluding the prefix) to generate either as a fixed length or as a length range.
        *
        * @default 1
        */
       length?:
         | number
         | {
             /**
-             * The minimum number of characters to generate after the prefix.
+             * The minimum length of the string (excluding the prefix) to generate.
              */
             min: number;
             /**
-             * The maximum number of characters to generate after the prefix.
+             * The maximum length of the string (excluding the prefix) to generate.
              */
             max: number;
           };
@@ -548,8 +548,8 @@ export class StringModule extends SimpleModuleBase {
   /**
    * Generates a given length string of digits.
    *
-   * @param options Either the number of characters or the options to use.
-   * @param options.length The number or range of digits to generate. Defaults to `1`.
+   * @param options Either the length of the string to generate or the optional options object.
+   * @param options.length The length of the string to generate either as a fixed length or as a length range. Defaults to `1`.
    * @param options.allowLeadingZeros Whether leading zeros are allowed or not. Defaults to `true`.
    * @param options.exclude An array of digits which should be excluded in the generated string. Defaults to `[]`.
    *
@@ -570,19 +570,19 @@ export class StringModule extends SimpleModuleBase {
       | number
       | {
           /**
-           * The number or range of digits to generate.
+           * The length of the string to generate either as a fixed length or as a length range.
            *
            * @default 1
            */
           length?:
             | number
             | {
                 /**
-                 * The minimum number of digits to generate.
+                 * The minimum length of the string to generate.
                  */
                 min: number;
                 /**
-                 * The maximum number of digits to generate.
+                 * The maximum length of the string to generate.
                  */
                 max: number;
               };
@@ -649,9 +649,9 @@ export class StringModule extends SimpleModuleBase {
   /**
    * Returns a string containing UTF-16 chars between 33 and 125 (`!` to `}`).
    *
-   * @param length Length of the generated string. Defaults to `10`.
-   * @param length.min The minimum number of characters to generate.
-   * @param length.max The maximum number of characters to generate.
+   * @param length The length of the string (excluding the prefix) to generate either as a fixed length or as a length range. Defaults to `10`.
+   * @param length.min The minimum length of the string to generate.
+   * @param length.max The maximum length of the string to generate.
    *
    * @example
    * faker.string.sample() // 'Zo!.:*e>wR'
@@ -665,11 +665,11 @@ export class StringModule extends SimpleModuleBase {
       | number
       | {
           /**
-           * The minimum number of characters to generate.
+           * The minimum length of the string to generate.
            */
           min: number;
           /**
-           * The maximum number of characters to generate.
+           * The maximum length of the string to generate.
            */
           max: number;
         } = 10
@@ -740,7 +740,7 @@ export class StringModule extends SimpleModuleBase {
   /**
    * Generates a [Nano ID](https://github.com/ai/nanoid).
    *
-   * @param length Length of the generated string. Defaults to `21`.
+   * @param length The length of the string to generate either as a fixed length or as a length range. Defaults to `21`.
    * @param length.min The minimum length of the Nano ID to generate.
    * @param length.max The maximum length of the Nano ID to generate.
    *
@@ -794,13 +794,14 @@ export class StringModule extends SimpleModuleBase {
 
   /**
    * Returns a string containing only special characters from the following list:
+   *
    * ```txt
    * ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~
    * ```
    *
-   * @param length Length of the generated string. Defaults to `1`.
-   * @param length.min The minimum number of special characters to generate.
-   * @param length.max The maximum number of special characters to generate.
+   * @param length The length of the string to generate either as a fixed length or as a length range. Defaults to `1`.
+   * @param length.min The minimum length of the string to generate.
+   * @param length.max The maximum length of the string to generate.
    *
    * @example
    * faker.string.symbol() // '$'
@@ -814,11 +815,11 @@ export class StringModule extends SimpleModuleBase {
       | number
       | {
           /**
-           * The minimum number of special characters to generate.
+           * The minimum length of the string to generate.
            */
           min: number;
           /**
-           * The maximum number of special characters to generate.
+           * The maximum length of the string to generate.
            */
           max: number;
         } = 1