From 18f14c8eb362e2d08d17a3746962c991f1d2815c Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Sun, 3 Nov 2024 11:41:19 +0100 Subject: [PATCH] docs(string): improve documentation for length parameters (#3216) --- src/modules/string/index.ts | 79 +++++++++++++++++++------------------ 1 file changed, 40 insertions(+), 39 deletions(-) diff --git a/src/modules/string/index.ts b/src/modules/string/index.ts index 67073242134..ac41238c47e 100644 --- a/src/modules/string/index.ts +++ b/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,7 +175,7 @@ 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 */ @@ -183,11 +183,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; }; @@ -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,7 +269,7 @@ 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 */ @@ -277,11 +277,11 @@ export class StringModule extends SimpleModuleBase { | 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,7 +362,7 @@ 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 */ @@ -370,11 +370,11 @@ export class StringModule extends SimpleModuleBase { | 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,7 +414,7 @@ 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 */ @@ -422,11 +422,11 @@ export class StringModule extends SimpleModuleBase { | 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,7 +472,7 @@ 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 */ @@ -480,11 +480,11 @@ export class StringModule extends SimpleModuleBase { | 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,7 +570,7 @@ 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 */ @@ -578,11 +578,11 @@ export class StringModule extends SimpleModuleBase { | 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