Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Merged
merged 6 commits into from
Nov 3, 2024
Merged

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

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
a947be7
docs(string): improve documentation for length parameters
ST-DDT Oct 22, 2024
555844e
Merge branch 'next' into docs/string/length
ST-DDT Oct 23, 2024
8e99a29
Merge branch 'next' into docs/string/length
ST-DDT Oct 26, 2024
bcfa98b
Merge branch 'next' into docs/string/length
ST-DDT Nov 2, 2024
1140767
Merge branch 'next' into docs/string/length
ST-DDT Nov 2, 2024
bd96994
Merge branch 'next' into docs/string/length
ST-DDT Nov 3, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 40 additions & 39 deletions src/modules/string/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*
Expand Down Expand Up @@ -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 `[]`.
*
Expand All @@ -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;
};
Expand Down Expand Up @@ -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 `[]`.
*
Expand All @@ -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;
};
Expand Down Expand Up @@ -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).
Expand All @@ -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;
};
Expand All @@ -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).
Expand All @@ -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;
};
Expand All @@ -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'`.
*
Expand All @@ -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;
};
Expand Down Expand Up @@ -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 `[]`.
*
Expand All @@ -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;
};
Expand Down Expand Up @@ -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'
Expand All @@ -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
Expand Down Expand Up @@ -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.
*
Expand Down Expand Up @@ -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() // '$'
Expand All @@ -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
Expand Down