docs: add image_providers jsdocs (#612)

faker-js · Mar 15, 2022 · 09487b6 · 09487b6
1 parent f038937
commit 09487b6
Show file tree

Hide file tree

Showing 3 changed files with 150 additions and 125 deletions.
diff --git 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
@@ -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(