docs: add image_providers jsdocs (#612)

3 files changed, 150 insertions, 125 deletions

diff --git a/src/image_providers/lorempicsum.ts b/src/image_providers/lorempicsum.ts
index 56553af0..9fed741e 100644
--- a/src/image_providers/lorempicsum.ts
+++ b/src/image_providers/lorempicsum.ts
@@ -1,15 +1,19 @@
 import type { Faker } from '..';
 
+/**
+ * Module to generate links to random images on `https://picsum.photos/`.
+ */
+// TODO ST-DDT 2022-03-11: Rename to picsum?
 export class LoremPicsum {
   constructor(private readonly faker: Faker) {}
 
   /**
-   * Search image from unsplash
+   * Generates a new picsum image url.
    *
-   * @param width
-   * @param height
-   * @param grayscale
-   * @param blur 1-10
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param grayscale Whether to return a grayscale image. Default to `false`.
+   * @param blur The optional level of blur to apply. Supports `1` - `10`.
    */
   image(
     width?: number,
@@ -21,22 +25,22 @@ export class LoremPicsum {
   }
 
   /**
-   * Search grayscale image from unsplash
+   * Generates a new picsum image url.
    *
-   * @param width
-   * @param height
-   * @param grayscale
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param grayscale Whether to return a grayscale image. Default to `false`.
    */
   imageGrayscale(width?: number, height?: number, grayscale?: boolean): string {
     return this.imageUrl(width, height, grayscale);
   }
 
   /**
-   * Search blurred image from unsplash
+   * Generates a new picsum image url.
    *
-   * @param width
-   * @param height
-   * @param blur 1-10
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param blur The optional level of blur to apply. Supports `1` - `10`.
    */
   imageBlurred(
     width?: number,
@@ -47,13 +51,13 @@ export class LoremPicsum {
   }
 
   /**
-   * Search same random image from unsplash, based on a seed
+   * Generates a new picsum image url.
    *
-   * @param width
-   * @param height
-   * @param grayscale
-   * @param blur 1-10
-   * @param seed
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param grayscale Whether to return a grayscale image. Default to `false`.
+   * @param blur The optional level of blur to apply. Supports `1` - `10`.
+   * @param seed The optional seed to use.
    */
   imageRandomSeeded(
     width?: number,
@@ -62,24 +66,30 @@ export class LoremPicsum {
     blur?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10,
     seed?: string
   ): string {
+    // TODO ST-DDT 2022-03-11: This method does the same as image url, maybe generate a seed, if it is missig?
     return this.imageUrl(width, height, grayscale, blur, seed);
   }
 
   /**
-   * avatar
+   * Returns a random avatar url.
+   *
+   * @example
+   * faker.internet.avatar()
+   * // 'https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHirLHGVixi6V76LhCkZUz6pnFt5AJBiyvHye/avatar/315.jpg'
    */
+  // TODO ST-DDT 2022-03-11: Deprecate this method as it is duplicate and has nothing to do with lorempicsum.
   avatar(): string {
     return this.faker.internet.avatar();
   }
 
   /**
-   * imageUrl
+   * Generates a new picsum image url.
    *
-   * @param width
-   * @param height
-   * @param grayscale
-   * @param blur 1-10
-   * @param seed
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param grayscale Whether to return a grayscale image. Default to `false`.
+   * @param blur The optional level of blur to apply. Supports `1` - `10`.
+   * @param seed The optional seed to use.
    */
   imageUrl(
     width?: number,
diff --git a/src/image_providers/lorempixel.ts b/src/image_providers/lorempixel.ts
index 2b7d5263..e58aa30b 100644
--- a/src/image_providers/lorempixel.ts
+++ b/src/image_providers/lorempixel.ts
@@ -1,14 +1,17 @@
 import type { Faker } from '..';
 
+/**
+ * Module to generate links to random images on `https://lorempixel.com/`.
+ */
 export class Lorempixel {
   constructor(private readonly faker: Faker) {}
 
   /**
-   * image
+   * Generates a new lorempixel image url for a random supported category.
    *
-   * @param width
-   * @param height
-   * @param randomize
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param randomize Whether to append a seed to the url. Defaults to `false`.
    */
   image(width?: number, height?: number, randomize?: boolean): string {
     const categories = [
@@ -34,19 +37,24 @@ export class Lorempixel {
   }
 
   /**
-   * avatar
+   * Returns a random avatar url.
+   *
+   * @example
+   * faker.internet.avatar()
+   * // 'https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHirLHGVixi6V76LhCkZUz6pnFt5AJBiyvHye/avatar/315.jpg'
    */
+  // TODO ST-DDT 2022-03-11: Deprecate this method as it is duplicate and has nothing to do with lorempixel.
   avatar(): string {
     return this.faker.internet.avatar();
   }
 
   /**
-   * imageUrl
+   * Generates a new lorempixel image url.
    *
-   * @param width
-   * @param height
-   * @param category
-   * @param randomize
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param category The category of the image to generate.
+   * @param randomize Whether to append a seed to the url. Defaults to `false`.
    */
   imageUrl(
     width?: number,
@@ -70,11 +78,11 @@ export class Lorempixel {
   }
 
   /**
-   * abstract
+   * Generates a new lorempixel image url using the "abstract" category.
    *
-   * @param width
-   * @param height
-   * @param randomize
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param randomize Whether to append a seed to the url. Defaults to `false`.
    */
   abstract(width?: number, height?: number, randomize?: boolean): string {
     return this.faker.image.lorempixel.imageUrl(
@@ -86,11 +94,11 @@ export class Lorempixel {
   }
 
   /**
-   * animals
+   * Generates a new lorempixel image url using the "animals" category.
    *
-   * @param width
-   * @param height
-   * @param randomize
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param randomize Whether to append a seed to the url. Defaults to `false`.
    */
   animals(width?: number, height?: number, randomize?: boolean): string {
     return this.faker.image.lorempixel.imageUrl(
@@ -102,11 +110,11 @@ export class Lorempixel {
   }
 
   /**
-   * business
+   * Generates a new lorempixel image url using the "business" category.
    *
-   * @param width
-   * @param height
-   * @param randomize
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param randomize Whether to append a seed to the url. Defaults to `false`.
    */
   business(width?: number, height?: number, randomize?: boolean): string {
     return this.faker.image.lorempixel.imageUrl(
@@ -118,11 +126,11 @@ export class Lorempixel {
   }
 
   /**
-   * cats
+   * Generates a new lorempixel image url using the "cats" category.
    *
-   * @param width
-   * @param height
-   * @param randomize
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param randomize Whether to append a seed to the url. Defaults to `false`.
    */
   cats(width?: number, height?: number, randomize?: boolean): string {
     return this.faker.image.lorempixel.imageUrl(
@@ -134,11 +142,11 @@ export class Lorempixel {
   }
 
   /**
-   * city
+   * Generates a new lorempixel image url using the "city" category.
    *
-   * @param width
-   * @param height
-   * @param randomize
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param randomize Whether to append a seed to the url. Defaults to `false`.
    */
   city(width?: number, height?: number, randomize?: boolean): string {
     return this.faker.image.lorempixel.imageUrl(
@@ -150,11 +158,11 @@ export class Lorempixel {
   }
 
   /**
-   * food
+   * Generates a new lorempixel image url using the "food" category.
    *
-   * @param width
-   * @param height
-   * @param randomize
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param randomize Whether to append a seed to the url. Defaults to `false`.
    */
   food(width?: number, height?: number, randomize?: boolean): string {
     return this.faker.image.lorempixel.imageUrl(
@@ -166,11 +174,11 @@ export class Lorempixel {
   }
 
   /**
-   * nightlife
+   * Generates a new lorempixel image url using the "nightlife" category.
    *
-   * @param width
-   * @param height
-   * @param randomize
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param randomize Whether to append a seed to the url. Defaults to `false`.
    */
   nightlife(width?: number, height?: number, randomize?: boolean): string {
     return this.faker.image.lorempixel.imageUrl(
@@ -182,11 +190,11 @@ export class Lorempixel {
   }
 
   /**
-   * fashion
+   * Generates a new lorempixel image url using the "fashion" category.
    *
-   * @param width
-   * @param height
-   * @param randomize
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param randomize Whether to append a seed to the url. Defaults to `false`.
    */
   fashion(width?: number, height?: number, randomize?: boolean): string {
     return this.faker.image.lorempixel.imageUrl(
@@ -198,11 +206,11 @@ export class Lorempixel {
   }
 
   /**
-   * people
+   * Generates a new lorempixel image url using the "people" category.
    *
-   * @param width
-   * @param height
-   * @param randomize
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param randomize Whether to append a seed to the url. Defaults to `false`.
    */
   people(width?: number, height?: number, randomize?: boolean): string {
     return this.faker.image.lorempixel.imageUrl(
@@ -214,11 +222,11 @@ export class Lorempixel {
   }
 
   /**
-   * nature
+   * Generates a new lorempixel image url using the "nature" category.
    *
-   * @param width
-   * @param height
-   * @param randomize
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param randomize Whether to append a seed to the url. Defaults to `false`.
    */
   nature(width?: number, height?: number, randomize?: boolean): string {
     return this.faker.image.lorempixel.imageUrl(
@@ -230,11 +238,11 @@ export class Lorempixel {
   }
 
   /**
-   * sports
+   * Generates a new lorempixel image url using the "sports" category.
    *
-   * @param width
-   * @param height
-   * @param randomize
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param randomize Whether to append a seed to the url. Defaults to `false`.
    */
   sports(width?: number, height?: number, randomize?: boolean): string {
     return this.faker.image.lorempixel.imageUrl(
@@ -246,11 +254,11 @@ export class Lorempixel {
   }
 
   /**
-   * technics
+   * Generates a new lorempixel image url using the "technics" category.
    *
-   * @param width
-   * @param height
-   * @param randomize
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param randomize Whether to append a seed to the url. Defaults to `false`.
    */
   technics(width?: number, height?: number, randomize?: boolean): string {
     return this.faker.image.lorempixel.imageUrl(
@@ -262,11 +270,11 @@ export class Lorempixel {
   }
 
   /**
-   * transport
+   * Generates a new lorempixel image url using the "transport" category.
    *
-   * @param width
-   * @param height
-   * @param randomize
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param randomize Whether to append a seed to the url. Defaults to `false`.
    */
   transport(width?: number, height?: number, randomize?: boolean): string {
     return this.faker.image.lorempixel.imageUrl(
diff --git a/src/image_providers/unsplash.ts b/src/image_providers/unsplash.ts
index 45fbdd6c..47157eb2 100644
--- a/src/image_providers/unsplash.ts
+++ b/src/image_providers/unsplash.ts
@@ -1,6 +1,10 @@
 import type { Faker } from '..';
 
+/**
+ * Module to generate links to random images on `https://source.unsplash.com/`.
+ */
 export class Unsplash {
+  // TODO ST-DDT 2022-03-11: Remove unused(?) constant
   categories = [
     'food',
     'nature',
@@ -13,30 +17,35 @@ export class Unsplash {
   constructor(private readonly faker: Faker) {}
 
   /**
-   * Search image from unsplash
+   * Generates a new unsplash image url for a random supported category.
    *
-   * @param width
-   * @param height
-   * @param keyword
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param keyword The image keywords to use.
    */
   image(width?: number, height?: number, keyword?: string): string {
     return this.imageUrl(width, height, undefined, keyword);
   }
 
   /**
-   * avatar
+   * Returns a random avatar url.
+   *
+   * @example
+   * faker.internet.avatar()
+   * // 'https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHirLHGVixi6V76LhCkZUz6pnFt5AJBiyvHye/avatar/315.jpg'
    */
+  // TODO ST-DDT 2022-03-11: Deprecate this method as it is duplicate and has nothing to do with unsplash.
   avatar(): string {
     return this.faker.internet.avatar();
   }
 
   /**
-   * imageUrl
+   * Generates a new unsplash image url.
    *
-   * @param width
-   * @param height
-   * @param category
-   * @param keyword
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param category The category of the image to generate.
+   * @param keyword The image keywords to use.
    */
   imageUrl(
     width?: number,
@@ -56,9 +65,7 @@ export class Unsplash {
     url += `/${width}x${height}`;
 
     if (typeof keyword !== 'undefined') {
-      const keywordFormat = new RegExp(
-        '^([A-Za-z0-9].+,[A-Za-z0-9]+)$|^([A-Za-z0-9]+)$'
-      );
+      const keywordFormat = /^([A-Za-z0-9].+,[A-Za-z0-9]+)$|^([A-Za-z0-9]+)$/;
       if (keywordFormat.test(keyword)) {
         url += '?' + keyword;
       }
@@ -68,44 +75,44 @@ export class Unsplash {
   }
 
   /**
-   * food
+   * Generates a new unsplash image url using the "food" category.
    *
-   * @param width
-   * @param height
-   * @param keyword
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param keyword The image keywords to use.
    */
   food(width?: number, height?: number, keyword?: string): string {
     return this.faker.image.unsplash.imageUrl(width, height, 'food', keyword);
   }
 
   /**
-   * people
+   * Generates a new unsplash image url using the "people" category.
    *
-   * @param width
-   * @param height
-   * @param keyword
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param keyword The image keywords to use.
    */
   people(width?: number, height?: number, keyword?: string): string {
     return this.faker.image.unsplash.imageUrl(width, height, 'people', keyword);
   }
 
   /**
-   * nature
+   * Generates a new unsplash image url using the "nature" category.
    *
-   * @param width
-   * @param height
-   * @param keyword
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param keyword The image keywords to use.
    */
   nature(width?: number, height?: number, keyword?: string): string {
     return this.faker.image.unsplash.imageUrl(width, height, 'nature', keyword);
   }
 
   /**
-   * technology
+   * Generates a new unsplash image url using the "technology" category.
    *
-   * @param width
-   * @param height
-   * @param keyword
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param keyword The image keywords to use.
    */
   technology(width?: number, height?: number, keyword?: string): string {
     return this.faker.image.unsplash.imageUrl(
@@ -117,11 +124,11 @@ export class Unsplash {
   }
 
   /**
-   * objects
+   * Generates a new unsplash image url using the "objects" category.
    *
-   * @param width
-   * @param height
-   * @param keyword
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param keyword The image keywords to use.
    */
   objects(width?: number, height?: number, keyword?: string): string {
     return this.faker.image.unsplash.imageUrl(
@@ -133,11 +140,11 @@ export class Unsplash {
   }
 
   /**
-   * buildings
+   * Generates a new unsplash image url using the "buildings" category.
    *
-   * @param width
-   * @param height
-   * @param keyword
+   * @param width The width of the image. Defaults to `640`.
+   * @param height The height of the image. Defaults to `480`.
+   * @param keyword The image keywords to use.
    */
   buildings(width?: number, height?: number, keyword?: string): string {
     return this.faker.image.unsplash.imageUrl(