docs(image): explain deprecation of category methods (#2040)

1 files changed, 85 insertions, 27 deletions

diff --git a/src/modules/image/index.ts b/src/modules/image/index.ts
index cce875ba..e7d26814 100644
--- a/src/modules/image/index.ts
+++ b/src/modules/image/index.ts
@@ -16,7 +16,7 @@ import { Unsplash } from './providers/unsplash';
  *
  * For a random user avatar image, use [`avatar()`](https://next.fakerjs.dev/api/image.html#avatar).
  *
- * This module previously also contained methods for specifically themed images like "fashion" or "food", but these are now deprecated. If you need more control over image type, you are recommended to use an image provider directly or provide your own set of placeholder images.
+ * This module previously also contained methods for specifically themed images like "fashion" or "food", but these are now deprecated. If you need more control over image type, you can request categorized images using [`urlLoremFlickr()`](https://next.fakerjs.dev/api/image.html#urlloremflickr), use an image provider directly or provide your own set of placeholder images.
  */
 export class ImageModule {
   /**
@@ -501,6 +501,9 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
+   * @see faker.image.url()
+   * @see faker.image.urlLoremFlickr()
+   *
    * @example
    * faker.image.abstract() // 'https://loremflickr.com/640/480/abstract'
    * faker.image.abstract(1234, 2345) // 'https://loremflickr.com/1234/2345/abstract'
@@ -508,12 +511,14 @@ export class ImageModule {
    *
    * @since 2.0.1
    *
-   * @deprecated Use `faker.image.url` instead.
+   * @deprecated Use `faker.image.urlLoremFlickr({ category: 'abstract' })` if you want an image from LoremFlickr in the correct category, or `faker.image.url()` if you just want any image.
+   *
    */
   abstract(width?: number, height?: number, randomize?: boolean): string {
     deprecated({
       deprecated: 'faker.image.abstract',
-      proposed: 'faker.image.url',
+      proposed:
+        "faker.image.urlLoremFlickr({ category: 'abstract' }) or faker.image.url",
       since: '8.0',
       until: '9.0',
     });
@@ -528,6 +533,9 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
+   * @see faker.image.url()
+   * @see faker.image.urlLoremFlickr()
+   *
    * @example
    * faker.image.animals() // 'https://loremflickr.com/640/480/animals'
    * faker.image.animals(1234, 2345) // 'https://loremflickr.com/1234/2345/animals'
@@ -535,12 +543,14 @@ export class ImageModule {
    *
    * @since 2.0.1
    *
-   * @deprecated Use `faker.image.url` instead.
+   * @deprecated Use `faker.image.urlLoremFlickr({ category: 'animals' })` if you want an image from LoremFlickr in the correct category, or `faker.image.url()` if you just want any image.
+   *
    */
   animals(width?: number, height?: number, randomize?: boolean): string {
     deprecated({
       deprecated: 'faker.image.animals',
-      proposed: 'faker.image.url',
+      proposed:
+        "faker.image.urlLoremFlickr({ category: 'animals' }) or faker.image.url",
       since: '8.0',
       until: '9.0',
     });
@@ -555,6 +565,9 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
+   * @see faker.image.url()
+   * @see faker.image.urlLoremFlickr()
+   *
    * @example
    * faker.image.business() // 'https://loremflickr.com/640/480/business'
    * faker.image.business(1234, 2345) // 'https://loremflickr.com/1234/2345/business'
@@ -562,12 +575,15 @@ export class ImageModule {
    *
    * @since 2.0.1
    *
-   * @deprecated Use `faker.image.url` instead.
+   * @deprecated Use `faker.image.urlLoremFlickr({ category: 'business' })` if you want an image from LoremFlickr in the correct category, or `faker.image.url()` if you just want any image.
+   *
+   *
    */
   business(width?: number, height?: number, randomize?: boolean): string {
     deprecated({
       deprecated: 'faker.image.business',
-      proposed: 'faker.image.url',
+      proposed:
+        "faker.image.urlLoremFlickr({ category: 'business' }) or faker.image.url",
       since: '8.0',
       until: '9.0',
     });
@@ -582,6 +598,9 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
+   * @see faker.image.url()
+   * @see faker.image.urlLoremFlickr()
+   *
    * @example
    * faker.image.cats() // 'https://loremflickr.com/640/480/cats'
    * faker.image.cats(1234, 2345) // 'https://loremflickr.com/1234/2345/cats'
@@ -589,12 +608,13 @@ export class ImageModule {
    *
    * @since 2.0.1
    *
-   * @deprecated Use `faker.image.url` instead.
+   * @deprecated Use `faker.image.urlLoremFlickr({ category: 'cats' })` if you want an image from LoremFlickr in the correct category, or `faker.image.url()` if you just want any image.
    */
   cats(width?: number, height?: number, randomize?: boolean): string {
     deprecated({
       deprecated: 'faker.image.cats',
-      proposed: 'faker.image.url',
+      proposed:
+        "faker.image.urlLoremFlickr({ category: 'cats' }) or faker.image.url",
       since: '8.0',
       until: '9.0',
     });
@@ -609,6 +629,9 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
+   * @see faker.image.url()
+   * @see faker.image.urlLoremFlickr()
+   *
    * @example
    * faker.image.city() // 'https://loremflickr.com/640/480/city'
    * faker.image.city(1234, 2345) // 'https://loremflickr.com/1234/2345/city'
@@ -616,12 +639,13 @@ export class ImageModule {
    *
    * @since 2.0.1
    *
-   * @deprecated Use `faker.image.url` instead.
+   * @deprecated Use `faker.image.urlLoremFlickr({ category: 'city' })` if you want an image from LoremFlickr in the correct category, or `faker.image.url()` if you just want any image.
    */
   city(width?: number, height?: number, randomize?: boolean): string {
     deprecated({
       deprecated: 'faker.image.city',
-      proposed: 'faker.image.url',
+      proposed:
+        "faker.image.urlLoremFlickr({ category: 'city' }) or faker.image.url",
       since: '8.0',
       until: '9.0',
     });
@@ -636,6 +660,9 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
+   * @see faker.image.url()
+   * @see faker.image.urlLoremFlickr()
+   *
    * @example
    * faker.image.food() // 'https://loremflickr.com/640/480/food'
    * faker.image.food(1234, 2345) // 'https://loremflickr.com/1234/2345/food'
@@ -643,12 +670,13 @@ export class ImageModule {
    *
    * @since 2.0.1
    *
-   * @deprecated Use `faker.image.url` instead.
+   * @deprecated Use `faker.image.urlLoremFlickr({ category: 'food' })` if you want an image from LoremFlickr in the correct category, or `faker.image.url()` if you just want any image.
    */
   food(width?: number, height?: number, randomize?: boolean): string {
     deprecated({
       deprecated: 'faker.image.food',
-      proposed: 'faker.image.url',
+      proposed:
+        "faker.image.urlLoremFlickr({ category: 'food' }) or faker.image.url",
       since: '8.0',
       until: '9.0',
     });
@@ -663,6 +691,9 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
+   * @see faker.image.url()
+   * @see faker.image.urlLoremFlickr()
+   *
    * @example
    * faker.image.nightlife() // 'https://loremflickr.com/640/480/nightlife'
    * faker.image.nightlife(1234, 2345) // 'https://loremflickr.com/1234/2345/nightlife'
@@ -670,12 +701,13 @@ export class ImageModule {
    *
    * @since 2.0.1
    *
-   * @deprecated Use `faker.image.url` instead.
+   * @deprecated Use `faker.image.urlLoremFlickr({ category: 'nightlife' })` if you want an image from LoremFlickr in the correct category, or `faker.image.url()` if you just want any image.
    */
   nightlife(width?: number, height?: number, randomize?: boolean): string {
     deprecated({
       deprecated: 'faker.image.nightlife',
-      proposed: 'faker.image.url',
+      proposed:
+        "faker.image.urlLoremFlickr({ category: 'nightlife' }) or faker.image.url",
       since: '8.0',
       until: '9.0',
     });
@@ -690,6 +722,9 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
+   * @see faker.image.url()
+   * @see faker.image.urlLoremFlickr()
+   *
    * @example
    * faker.image.fashion() // 'https://loremflickr.com/640/480/fashion'
    * faker.image.fashion(1234, 2345) // 'https://loremflickr.com/1234/2345/fashion'
@@ -697,12 +732,13 @@ export class ImageModule {
    *
    * @since 2.0.1
    *
-   * @deprecated Use `faker.image.url` instead.
+   * @deprecated Use `faker.image.urlLoremFlickr({ category: 'fashion' })` if you want an image from LoremFlickr in the correct category, or `faker.image.url()` if you just want any image.
    */
   fashion(width?: number, height?: number, randomize?: boolean): string {
     deprecated({
       deprecated: 'faker.image.fashion',
-      proposed: 'faker.image.url',
+      proposed:
+        "faker.image.urlLoremFlickr({ category: 'fashion' }) or faker.image.url",
       since: '8.0',
       until: '9.0',
     });
@@ -717,6 +753,9 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
+   * @see faker.image.url()
+   * @see faker.image.urlLoremFlickr()
+   *
    * @example
    * faker.image.people() // 'https://loremflickr.com/640/480/people'
    * faker.image.people(1234, 2345) // 'https://loremflickr.com/1234/2345/people'
@@ -724,12 +763,13 @@ export class ImageModule {
    *
    * @since 2.0.1
    *
-   * @deprecated Use `faker.image.url` instead.
+   * @deprecated Use `faker.image.urlLoremFlickr({ category: 'people' })` if you want an image from LoremFlickr in the correct category, or `faker.image.url()` if you just want any image.
    */
   people(width?: number, height?: number, randomize?: boolean): string {
     deprecated({
       deprecated: 'faker.image.people',
-      proposed: 'faker.image.url',
+      proposed:
+        "faker.image.urlLoremFlickr({ category: 'people' }) or faker.image.url",
       since: '8.0',
       until: '9.0',
     });
@@ -744,6 +784,9 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
+   * @see faker.image.url()
+   * @see faker.image.urlLoremFlickr()
+   *
    * @example
    * faker.image.nature() // 'https://loremflickr.com/640/480/nature'
    * faker.image.nature(1234, 2345) // 'https://loremflickr.com/1234/2345/nature'
@@ -751,12 +794,13 @@ export class ImageModule {
    *
    * @since 2.0.1
    *
-   * @deprecated Use `faker.image.url` instead.
+   * @deprecated Use `faker.image.urlLoremFlickr({ category: 'nature' })` if you want an image from LoremFlickr in the correct category, or `faker.image.url()` if you just want any image.
    */
   nature(width?: number, height?: number, randomize?: boolean): string {
     deprecated({
       deprecated: 'faker.image.nature',
-      proposed: 'faker.image.url',
+      proposed:
+        "faker.image.urlLoremFlickr({ category: 'nature' }) or faker.image.url",
       since: '8.0',
       until: '9.0',
     });
@@ -771,6 +815,9 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
+   * @see faker.image.url()
+   * @see faker.image.urlLoremFlickr()
+   *
    * @example
    * faker.image.sports() // 'https://loremflickr.com/640/480/sports'
    * faker.image.sports(1234, 2345) // 'https://loremflickr.com/1234/2345/sports'
@@ -778,12 +825,13 @@ export class ImageModule {
    *
    * @since 2.0.1
    *
-   * @deprecated Use `faker.image.url` instead.
+   * @deprecated Use `faker.image.urlLoremFlickr({ category: 'sports' })` if you want an image from LoremFlickr in the correct category, or `faker.image.url()` if you just want any image.
    */
   sports(width?: number, height?: number, randomize?: boolean): string {
     deprecated({
       deprecated: 'faker.image.sports',
-      proposed: 'faker.image.url',
+      proposed:
+        "faker.image.urlLoremFlickr({ category: 'sports' }) or faker.image.url",
       since: '8.0',
       until: '9.0',
     });
@@ -798,6 +846,9 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
+   * @see faker.image.url()
+   * @see faker.image.urlLoremFlickr()
+   *
    * @example
    * faker.image.technics() // 'https://loremflickr.com/640/480/technics'
    * faker.image.technics(1234, 2345) // 'https://loremflickr.com/1234/2345/technics'
@@ -805,12 +856,13 @@ export class ImageModule {
    *
    * @since 2.0.1
    *
-   * @deprecated Use `faker.image.url` instead.
+   * @deprecated Use `faker.image.urlLoremFlickr({ category: 'technics' })` if you want an image from LoremFlickr in the correct category, or `faker.image.url()` if you just want any image.
    */
   technics(width?: number, height?: number, randomize?: boolean): string {
     deprecated({
       deprecated: 'faker.image.technics',
-      proposed: 'faker.image.url',
+      proposed:
+        "faker.image.urlLoremFlickr({ category: 'technics' }) or faker.image.url",
       since: '8.0',
       until: '9.0',
     });
@@ -825,6 +877,9 @@ export class ImageModule {
    * @param height The height of the image. Defaults to `480`.
    * @param randomize Whether to randomize the image or not. Defaults to `false`.
    *
+   * @see faker.image.url()
+   * @see faker.image.urlLoremFlickr()
+   *
    * @example
    * faker.image.transport() // 'https://loremflickr.com/640/480/transport'
    * faker.image.transport(1234, 2345) // 'https://loremflickr.com/1234/2345/transport'
@@ -832,12 +887,15 @@ export class ImageModule {
    *
    * @since 2.0.1
    *
-   * @deprecated Use `faker.image.url` instead.
+   * @deprecated Use `faker.image.urlLoremFlickr({ category: 'transport' })` if you want an image from LoremFlickr in the correct category, or `faker.image.url()` if you just want any image.
+   *
+   *
    */
   transport(width?: number, height?: number, randomize?: boolean): string {
     deprecated({
       deprecated: 'faker.image.transport',
-      proposed: 'faker.image.url',
+      proposed:
+        "faker.image.urlLoremFlickr({ category: 'transport' }) or faker.image.url",
       since: '8.0',
       until: '9.0',
     });