chore: fix JSDoc comments in datatype.ts (#337)

1 files changed, 78 insertions, 34 deletions

diff --git a/src/datatype.ts b/src/datatype.ts
index ef7f5709..2fbc5c6b 100644
--- a/src/datatype.ts
+++ b/src/datatype.ts
@@ -19,10 +19,21 @@ export class Datatype {
   }
 
   /**
-   * Returns a single random number based on a max number or range.
+   * Returns a single random number between zero and the given max value or the given range with the specified precision.
+   * The bounds are inclusive.
    *
-   * @method faker.datatype.number
-   * @param options
+   * @param options Maximum value or options object.
+   * @param options.min Lower bound for generated number. Defaults to `0`.
+   * @param options.max Upper bound for generated number. Defaults to `99999`.
+   * @param options.precision Precision of the generated number. Defaults to `1`.
+   *
+   * @example
+   * faker.datatype.number() // 55422
+   * faker.datatype.number(100) // 52
+   * faker.datatype.number({ min: 1000000 }) // 431433
+   * faker.datatype.number({ max: 100 }) // 42
+   * faker.datatype.number({ precision: 0.01 }) // 64246.18
+   * faker.datatype.number({ min: 10, max: 100, precision: 0.01 }) // 36.94
    */
   number(
     options?: number | { min?: number; max?: number; precision?: number }
@@ -64,10 +75,20 @@ export class Datatype {
   }
 
   /**
-   * Returns a single random floating-point number based on a max number or range.
+   * Returns a single random floating-point number for the given precision or range and precision.
+   *
+   * @param options Precision or options object.
+   * @param options.min Lower bound for generated number. Defaults to `0`.
+   * @param options.max Upper bound for generated number. Defaults to `99999`.
+   * @param options.precision Precision of the generated number. Defaults to `0.01`.
    *
-   * @method faker.datatype.float
-   * @param options
+   * @example
+   * faker.datatype.float() // 51696.36
+   * faker.datatype.float(0.1) // 52023.2
+   * faker.datatype.float({ min: 1000000 }) // 212859.76
+   * faker.datatype.float({ max: 100 }) // 28.11
+   * faker.datatype.float({ precision: 0.1 }) // 84055.3
+   * faker.datatype.float({ min: 10, max: 100, precision: 0.001 }) // 57.315
    */
   float(
     options?: number | { min?: number; max?: number; precision?: number }
@@ -89,11 +110,16 @@ export class Datatype {
   }
 
   /**
-   * Returns a Date object using a random number of milliseconds since 1. Jan 1970 UTC
-   * Caveat: seeding is not working
+   * Returns a Date object using a random number of milliseconds since
+   * the [Unix Epoch](https://en.wikipedia.org/wiki/Unix_time) (1 January 1970 UTC).
    *
-   * @method faker.datatype.datetime
-   * @param options pass min OR max as number of milliseconds since 1. Jan 1970 UTC
+   * @param options Max number of milliseconds since unix epoch or options object
+   * @param options.min Lower bound for milliseconds since base date.
+   *    When not provided or smaller than `-8640000000000000`, `1990-01-01` is considered
+   *    as minimum generated date. Defaults to `633880849813`.
+   * @param options.max Upper bound for milliseconds since base date.
+   *    When not provided or larger than `8640000000000000`, `2100-01-01` is considered
+   *    as maximum generated date.
    */
   datetime(options?: number | { min?: number; max?: number }): Date {
     const minMax = 8640000000000000;
@@ -113,12 +139,15 @@ export class Datatype {
   }
 
   /**
-   * Returns a string, containing UTF-16 chars between 33 and 125 ('!' to '}')
+   * Returns a string containing UTF-16 chars between 33 and 125 ('!' to '}').
+   *
+   * @param length Length of the generated string. Max length is `2^20`. Defaults to `10`.
    *
-   * @method faker.datatype.string
-   * @param length length of generated string, default = 10, max length = 2^20
+   * @example
+   * faker.datatype.string() // 'Zo!.:*e>wR'
+   * faker.datatype.string(5) // '6Bye8'
    */
-  string(length: number = 10): string {
+  string(length = 10): string {
     const maxLength = Math.pow(2, 20);
     if (length >= maxLength) {
       length = maxLength;
@@ -141,9 +170,10 @@ export class Datatype {
   }
 
   /**
-   * uuid
+   * Returns a UUID v4 ([Universally Unique Identifier](https://en.wikipedia.org/wiki/Universally_unique_identifier)).
    *
-   * @method faker.datatype.uuid
+   * @example
+   * faker.datatype.uuid() // '4136cd0b-d90b-4af7-b485-5d1ded8db252'
    */
   uuid(): string {
     const RFC4122_TEMPLATE = 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx';
@@ -156,23 +186,28 @@ export class Datatype {
   }
 
   /**
-   * boolean
+   * Returns the boolean value true or false.
    *
-   * @method faker.datatype.boolean
+   * @example
+   * faker.datatype.boolean() // false
    */
   boolean(): boolean {
     return !!this.faker.datatype.number(1);
   }
 
   /**
-   * hexaDecimal
+   * Returns a [hexadecimal](https://en.wikipedia.org/wiki/Hexadecimal) number.
    *
-   * @method faker.datatype.hexaDecimal
-   * @param count defaults to 1
+   * @param length Length of the generated number. Defaults to `1`.
+   *
+   * @example
+   * faker.datatype.hexaDecimal() // '0xb'
+   * faker.datatype.hexaDecimal(10) // '0xaE13F044fb'
    */
-  hexaDecimal(count: number = 1): string {
+  hexaDecimal(length = 1): string {
     let wholeString = '';
-    for (let i = 0; i < count; i++) {
+
+    for (let i = 0; i < length; i++) {
       wholeString += this.faker.random.arrayElement([
         '0',
         '1',
@@ -203,14 +238,15 @@ export class Datatype {
   }
 
   /**
-   * Returns json object with 7 pre-defined properties
+   * Returns a string representing JSON object with 7 pre-defined properties.
    *
-   * @method faker.datatype.json
+   * @example
+   * faker.datatype.json() // `{"foo":"mxz.v8ISij","bar":29154,"bike":8658,"a":"GxTlw$nuC:","b":40693,"name":"%'<FTou{7X","prop":"X(bd4iT>77"}`
    */
   json(): string {
     const properties = ['foo', 'bar', 'bike', 'a', 'b', 'name', 'prop'];
-
     const returnObject: Record<string, string | number> = {};
+
     properties.forEach((prop) => {
       returnObject[prop] = this.faker.datatype.boolean()
         ? this.faker.datatype.string()
@@ -221,13 +257,15 @@ export class Datatype {
   }
 
   /**
-   * Returns an array with values generated by faker.datatype.number and faker.datatype.string
+   * Returns an array with random strings and numbers.
+   *
+   * @param length Size of the returned array. Defaults to `10`.
    *
-   * @method faker.datatype.array
-   * @param length length of the returned array
+   * @example
+   * faker.datatype.array() // [ 94099, 85352, 'Hz%T.C\\l;8', '|#gmtw3otS', '2>:rJ|3$&d', 56864, 'Ss2-p0RXSI', 51084, 2039, 'mNEU[.r0Vf' ]
+   * faker.datatype.array(3) // [ 61845, 'SK7H$W3:d*', 'm[%7N8*GVK' ]
    */
-
-  array(length: number = 10): Array<string | number> {
+  array(length = 10): Array<string | number> {
     const returnArray = new Array(length);
     for (let i = 0; i < length; i++) {
       returnArray[i] = this.faker.datatype.boolean()
@@ -238,10 +276,16 @@ export class Datatype {
   }
 
   /**
-   * Returns a Big Integer with values generated by faker.datatype.bigInt
+   * Returns a [BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type) number.
+   *
+   * @param value When provided, this method simply converts it to `BigInt` type.
    *
-   * @method faker.datatype.bigInt
-   * @param value
+   * @example
+   * faker.datatype.bigInt() // 8507209999914928n
+   * faker.datatype.bigInt('156') // 156n
+   * faker.datatype.bigInt(30) // 30n
+   * faker.datatype.bigInt(3000n) // 3000n
+   * faker.datatype.bigInt(true) // 1n
    */
   bigInt(value?: string | number | bigint | boolean): bigint {
     if (value === undefined) {