From 09487b6b3a6e6cc3de0303851b9913ecdf1390dc Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Tue, 15 Mar 2022 16:19:03 +0100 Subject: [PATCH] docs: add image_providers jsdocs (#612) --- src/image_providers/lorempicsum.ts | 62 ++++++++------ src/image_providers/lorempixel.ts | 132 +++++++++++++++-------------- src/image_providers/unsplash.ts | 81 ++++++++++-------- 3 files changed, 150 insertions(+), 125 deletions(-) diff --git a/src/image_providers/lorempicsum.ts b/src/image_providers/lorempicsum.ts index 56553af07a0..9fed741ed5f 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 2b7d526300c..e58aa30b844 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 45fbdd6c527..47157eb20cf 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(