docs: add overview guides to specific modules (#1929)

1 files changed, 10 insertions, 0 deletions

diff --git a/src/modules/image/index.ts b/src/modules/image/index.ts
index 17d076cc..9ec579ec 100644
--- a/src/modules/image/index.ts
+++ b/src/modules/image/index.ts
@@ -7,6 +7,16 @@ import { Unsplash } from './providers/unsplash';
 
 /**
  * Module to generate images.
+ *
+ * ### Overview
+ *
+ * For a random image, use [`url()`](https://next.fakerjs.dev/api/image.html#url). This will not return the image directly but a URL pointing to an image from one of two demo image providers "Picsum" and "LoremFlickr". You can request an image specifically from one of two providers using [`urlLoremFlickr()`](https://next.fakerjs.dev/api/image.html#urlloremflickr) or [`urlPicsum()`](https://next.fakerjs.dev/api/image.html#urlpicsum).
+ *
+ * For a random placeholder image containing only solid color and text, use [`urlPlaceholder()`](https://next.fakerjs.dev/api/image.html#urlplaceholder) (uses a third-party service) or [`dataUri()`](https://next.fakerjs.dev/api/image.html#datauri) (returns a SVG string).
+ *
+ * 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.
  */
 export class ImageModule {
   /**