docs: improve internet jsdocs (#447)

1 files changed, 97 insertions, 215 deletions

diff --git a/src/internet.ts b/src/internet.ts
index ff227dbf..995f62b0 100644
--- a/src/internet.ts
+++ b/src/internet.ts
@@ -2,6 +2,9 @@ import type { Faker } from '.';
 
 import * as random_ua from './vendor/user-agent';
 
+/**
+ * Module to generate internet related entries.
+ */
 export class Internet {
   constructor(private readonly faker: Faker) {
     // Bind `this` so namespaced is working correctly
@@ -11,178 +14,14 @@ export class Internet {
       }
       this[name] = this[name].bind(this);
     }
-
-    // TODO @Shinigami92 2022-01-11: We should find a better strategy as assigning this property to a function
-    // @ts-expect-error
-    this.avatar.schema = {
-      description: 'Generates a URL for an avatar.',
-      sampleResults: [
-        'https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHirLHGVixi6V76LhCkZUz6pnFt5AJBiyvHye/avatar/754.jpg',
-      ],
-    };
-    // @ts-expect-error
-    this.email.schema = {
-      description:
-        'Generates a valid email address based on optional input criteria',
-      sampleResults: ['[email protected]'],
-      properties: {
-        firstName: {
-          type: 'string',
-          required: false,
-          description: 'The first name of the user',
-        },
-        lastName: {
-          type: 'string',
-          required: false,
-          description: 'The last name of the user',
-        },
-        provider: {
-          type: 'string',
-          required: false,
-          description: 'The domain of the user',
-        },
-      },
-    };
-    // @ts-expect-error
-    this.userName.schema = {
-      description:
-        'Generates a username based on one of several patterns. The pattern is chosen randomly.',
-      sampleResults: [
-        'Kirstin39',
-        'Kirstin.Smith',
-        'Kirstin.Smith39',
-        'KirstinSmith',
-        'KirstinSmith39',
-      ],
-      properties: {
-        firstName: {
-          type: 'string',
-          required: false,
-          description: 'The first name of the user',
-        },
-        lastName: {
-          type: 'string',
-          required: false,
-          description: 'The last name of the user',
-        },
-      },
-    };
-    // @ts-expect-error
-    this.protocol.schema = {
-      description: 'Randomly generates http or https',
-      sampleResults: ['https', 'http'],
-    };
-    // @ts-expect-error
-    this.httpMethod.schema = {
-      description:
-        'Randomly generates HTTP Methods (GET, POST, PUT, DELETE, PATCH)',
-      sampleResults: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
-    };
-    // @ts-expect-error
-    this.url.schema = {
-      description:
-        'Generates a random URL. The URL could be secure or insecure.',
-      sampleResults: ['http://rashawn.name', 'https://rashawn.name'],
-    };
-    // @ts-expect-error
-    this.domainName.schema = {
-      description: 'Generates a random domain name.',
-      sampleResults: ['marvin.org'],
-    };
-    // @ts-expect-error
-    this.domainSuffix.schema = {
-      description: 'Generates a random domain suffix.',
-      sampleResults: ['net'],
-    };
-    // @ts-expect-error
-    this.domainWord.schema = {
-      description: 'Generates a random domain word.',
-      sampleResults: ['alyce'],
-    };
-    // @ts-expect-error
-    this.ip.schema = {
-      description: 'Generates a random IP.',
-      sampleResults: ['97.238.241.11'],
-    };
-    // @ts-expect-error
-    this.ipv6.schema = {
-      description: 'Generates a random IPv6 address.',
-      sampleResults: ['2001:0db8:6276:b1a7:5213:22f1:25df:c8a0'],
-    };
-    // @ts-expect-error
-    this.port.schema = {
-      description: 'Generates a random port number.',
-      sampleResults: ['4422'],
-    };
-    // @ts-expect-error
-    this.userAgent.schema = {
-      description: 'Generates a random user agent.',
-      sampleResults: [
-        'Mozilla/5.0 (Macintosh; U; PPC Mac OS X 10_7_5 rv:6.0; SL) AppleWebKit/532.0.1 (KHTML, like Gecko) Version/7.1.6 Safari/532.0.1',
-      ],
-    };
-    // @ts-expect-error
-    this.color.schema = {
-      description: 'Generates a random hexadecimal color.',
-      sampleResults: ['#06267f'],
-      properties: {
-        baseRed255: {
-          type: 'number',
-          required: false,
-          description: 'The red value. Valid values are 0 - 255.',
-        },
-        baseGreen255: {
-          type: 'number',
-          required: false,
-          description: 'The green value. Valid values are 0 - 255.',
-        },
-        baseBlue255: {
-          type: 'number',
-          required: false,
-          description: 'The blue value. Valid values are 0 - 255.',
-        },
-      },
-    };
-    // @ts-expect-error
-    this.mac.schema = {
-      description: 'Generates a random mac address.',
-      sampleResults: ['78:06:cc:ae:b3:81'],
-    };
-    // @ts-expect-error
-    this.password.schema = {
-      description: 'Generates a random password.',
-      sampleResults: ['AM7zl6Mg', 'susejofe'],
-      properties: {
-        length: {
-          type: 'number',
-          required: false,
-          description: 'The number of characters in the password.',
-        },
-        memorable: {
-          type: 'boolean',
-          required: false,
-          description: 'Whether a password should be easy to remember.',
-        },
-        pattern: {
-          type: 'regex',
-          required: false,
-          description:
-            'A regex to match each character of the password against. This parameter will be negated if the memorable setting is turned on.',
-        },
-        prefix: {
-          type: 'string',
-          required: false,
-          description:
-            'A value to prepend to the generated password. The prefix counts towards the length of the password.',
-        },
-      },
-    };
   }
 
   /**
-   * avatar
+   * Returns a random avatar url.
    *
-   * @method faker.internet.avatar
+   * @example
+   * faker.internet.avatar()
+   * // 'https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHirLHGVixi6V76LhCkZUz6pnFt5AJBiyvHye/avatar/315.jpg'
    */
   avatar(): string {
     return `https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHirLHGVixi6V76LhCkZUz6pnFt5AJBiyvHye/avatar/${this.faker.datatype.number(
@@ -191,12 +30,16 @@ export class Internet {
   }
 
   /**
-   * email
+   * Generates an email address using the given person's name as base.
+   *
+   * @param firstName The optional first name to use. If not specified, a random one will be chosen.
+   * @param lastName The optional last name to use. If not specified, a random one will be chosen.
+   * @param provider The mail provider domain to use. If not specified, a random free mail provider will be chosen.
    *
-   * @method faker.internet.email
-   * @param firstName
-   * @param lastName
-   * @param provider
+   * @example
+   * faker.internet.email() // '[email protected]'
+   * faker.internet.email('Jeanne', 'Doe') // '[email protected]'
+   * faker.internet.email('Jeanne', 'Doe', 'example.fakerjs.dev') // '[email protected]'
    */
   email(firstName?: string, lastName?: string, provider?: string): string {
     provider =
@@ -214,11 +57,14 @@ export class Internet {
   }
 
   /**
-   * exampleEmail
+   * Generates an email address using an example mail provider using the given person's name as base.
+   *
+   * @param firstName The optional first name to use. If not specified, a random one will be chosen.
+   * @param lastName The optional last name to use. If not specified, a random one will be chosen.
    *
-   * @method faker.internet.exampleEmail
-   * @param firstName
-   * @param lastName
+   * @example
+   * faker.internet.exampleEmail() // '[email protected]'
+   * faker.internet.exampleEmail('Jeanne', 'Doe') // '[email protected]'
    */
   exampleEmail(firstName?: string, lastName?: string): string {
     const provider = this.faker.random.arrayElement(
@@ -228,11 +74,14 @@ export class Internet {
   }
 
   /**
-   * userName
+   * Generates a username using the given person's name as base.
    *
-   * @method faker.internet.userName
-   * @param firstName
-   * @param lastName
+   * @param firstName The optional first name to use. If not specified, a random one will be chosen.
+   * @param lastName The optional last name to use. If not specified, a random one will be chosen.
+   *
+   * @example
+   * faker.internet.userName() // 'Nettie_Zboncak40'
+   * faker.internet.userName('Jeanne', 'Doe') // 'Jeanne98'
    */
   userName(firstName?: string, lastName?: string): string {
     let result: string;
@@ -259,9 +108,11 @@ export class Internet {
   }
 
   /**
-   * protocol
+   * Returns a random web protocol. Either `http` or `https`.
    *
-   * @method faker.internet.protocol
+   * @example
+   * faker.internet.protocol() // 'http'
+   * faker.internet.protocol() // 'https'
    */
   protocol(): 'http' | 'https' {
     const protocols: ['http', 'https'] = ['http', 'https'];
@@ -269,9 +120,18 @@ export class Internet {
   }
 
   /**
-   * method
+   * Returns a random http method.
+   *
+   * Can be either of the following:
+   *
+   * - `GET`
+   * - `POST`
+   * - `PUT`
+   * - `DELETE`
+   * - `PATCH`
    *
-   * @method faker.internet.httpMethod
+   * @example
+   * faker.internet.httpMethod() // 'PATCH'
    */
   httpMethod(): 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' {
     const httpMethods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'] = [
@@ -285,9 +145,10 @@ export class Internet {
   }
 
   /**
-   * url
+   * Generates a random url.
    *
-   * @method faker.internet.url
+   * @example
+   * faker.internet.url() // 'https://remarkable-hackwork.info'
    */
   url(): string {
     return (
@@ -296,9 +157,10 @@ export class Internet {
   }
 
   /**
-   * domainName
+   * Generates a random domain name.
    *
-   * @method faker.internet.domainName
+   * @example
+   * faker.internet.domainName() // 'slow-timer.info'
    */
   domainName(): string {
     return (
@@ -309,9 +171,11 @@ export class Internet {
   }
 
   /**
-   * domainSuffix
+   * Returns a random domain suffix.
    *
-   * @method faker.internet.domainSuffix
+   * @example
+   * faker.internet.domainSuffix() // 'com'
+   * faker.internet.domainSuffix() // 'name'
    */
   domainSuffix(): string {
     return this.faker.random.arrayElement(
@@ -320,9 +184,11 @@ export class Internet {
   }
 
   /**
-   * domainWord
+   * Generates a random domain word.
    *
-   * @method faker.internet.domainWord
+   * @example
+   * faker.internet.domainWord() // 'close-reality'
+   * faker.internet.domainWord() // 'weird-cytoplasm'
    */
   domainWord(): string {
     return (this.faker.word.adjective() + '-' + this.faker.word.noun())
@@ -333,9 +199,10 @@ export class Internet {
   }
 
   /**
-   * ip
+   * Generates a random IPv4 address.
    *
-   * @method faker.internet.ip
+   * @example
+   * faker.internet.ip() // '245.108.222.0'
    */
   // TODO @Shinigami92 2022-01-23: Add ipv4 alias
   ip(): string {
@@ -352,9 +219,10 @@ export class Internet {
   }
 
   /**
-   * ipv6
+   * Generates a random IPv6 address.
    *
-   * @method faker.internet.ipv6
+   * @example
+   * faker.internet.ipv6() // '269f:1230:73e3:318d:842b:daab:326d:897b'
    */
   ipv6(): string {
     const randHash = () => {
@@ -390,30 +258,36 @@ export class Internet {
   }
 
   /**
-   * port
+   * Generates a random port number.
    *
-   * @method faker.internet.port
+   * @example
+   * faker.internet.port() // '9414'
    */
   port(): number {
     return this.faker.datatype.number({ min: 0, max: 65535 });
   }
 
   /**
-   * userAgent
+   * Generates a random user agent string.
    *
-   * @method faker.internet.userAgent
+   * @example
+   * faker.internet.userAgent()
+   * // 'Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_8_8)  AppleWebKit/536.0.2 (KHTML, like Gecko) Chrome/27.0.849.0 Safari/536.0.2'
    */
   userAgent(): string {
     return random_ua.generate(this.faker);
   }
 
   /**
-   * color
+   * Generates a random css hex color code.
    *
-   * @method faker.internet.color
-   * @param baseRed255
-   * @param baseGreen255
-   * @param baseBlue255
+   * @param baseRed255 The optional base red. Used for aesthetically pleasing color palettes. Supports values between `0` and `255`. Defaults to `0`.
+   * @param baseGreen255 The optional base green. Used for aesthetically pleasing color palettes. Supports values between `0` and `255`. Defaults to `0`.
+   * @param baseBlue255 The optional base blue. Used for aesthetically pleasing color palettes. Supports values between `0` and `255`. Defaults to `0`.
+   *
+   * @example
+   * faker.internet.color() // '#30686e'
+   * faker.internet.color(100, 100, 100) // '#4e5f8b'
    */
   color(
     baseRed255: number = 0,
@@ -443,10 +317,12 @@ export class Internet {
   }
 
   /**
-   * mac
+   * Generates a random mac address.
+   *
+   * @param sep The optional separator to use. Can be either `':'`, `'-'` or `''`. Defaults to `':'`
    *
-   * @method faker.internet.mac
-   * @param sep
+   * @example
+   * faker.internet.mac() // '32:8e:2e:09:c6:05'
    */
   mac(sep?: string): string {
     let i: number;
@@ -469,13 +345,19 @@ export class Internet {
   }
 
   /**
-   * password
+   * Generates a random password.
+   *
+   * @param len The length of the password to generate. Defaults to `15`.
+   * @param memorable Whether the generated password should be memorable. Defaults to `false`.
+   * @param pattern The pattern that all chars should match should match. Defaults to `/\w/`.
+   * @param prefix The prefix to use. Defaults to `''`
    *
-   * @method faker.internet.password
-   * @param len
-   * @param memorable
-   * @param pattern
-   * @param prefix
+   * @example
+   * faker.internet.password() // '89G1wJuBLbGziIs'
+   * faker.internet.password(20) // 'aF55c_8O9kZaPOrysFB_'
+   * faker.internet.password(20, true) // 'lawetimufozujosodedi'
+   * faker.internet.password(20, true, /[A-Z]/) // 'HMAQDFFYLDDUTBKVNFVS'
+   * faker.internet.password(20, true, /[A-Z]/, 'Hello ') // 'Hello IREOXTDWPERQSB'
    */
   password(
     len?: number,