From 3562e872530b3610d95be71aa6f4f7fdfef7134f Mon Sep 17 00:00:00 2001
From: Matt Mayer <152770+matthewmayer@users.noreply.github.com>
Date: Wed, 29 Mar 2023 20:36:46 +0700
Subject: docs: add overview guides to specific modules (#1929)

---
 docs/api/ApiIndex.vue           | 12 +++++++-----
 scripts/apidoc/moduleMethods.ts |  4 ++--
 scripts/apidoc/signature.ts     |  4 ++++
 src/modules/airline/index.ts    | 16 +++++++++++++++-
 src/modules/animal/index.ts     |  8 ++++++++
 src/modules/color/index.ts      |  6 ++++++
 src/modules/commerce/index.ts   |  8 ++++++++
 src/modules/company/index.ts    | 11 +++++++++++
 src/modules/database/index.ts   |  6 ++++++
 src/modules/datatype/index.ts   |  6 ++++++
 src/modules/date/index.ts       | 12 ++++++++++++
 src/modules/finance/index.ts    | 12 +++++++++++-
 src/modules/git/index.ts        |  4 ++++
 src/modules/hacker/index.ts     | 12 ++++++++++++
 src/modules/helpers/index.ts    |  8 ++++++++
 src/modules/image/index.ts      | 10 ++++++++++
 src/modules/internet/index.ts   | 10 ++++++++++
 src/modules/location/index.ts   | 10 +++++++++-
 src/modules/lorem/index.ts      |  8 ++++++++
 src/modules/music/index.ts      |  4 ++++
 src/modules/number/index.ts     | 11 +++++++++++
 src/modules/person/index.ts     | 19 ++++++++++++++++++-
 src/modules/phone/index.ts      |  4 ++++
 src/modules/random/index.ts     |  4 ++++
 src/modules/science/index.ts    |  4 ++++
 src/modules/string/index.ts     | 13 +++++++++++++
 src/modules/vehicle/index.ts    |  6 ++++++
 27 files changed, 221 insertions(+), 11 deletions(-)

diff --git a/docs/api/ApiIndex.vue b/docs/api/ApiIndex.vue
index 0d421775..55efaeca 100644
--- a/docs/api/ApiIndex.vue
+++ b/docs/api/ApiIndex.vue
@@ -96,7 +96,9 @@ onUnmounted(() => window.removeEventListener('keydown', apiSearchFocusHandler));
       <h2 :id="slugify(section.text)">{{ section.text }}</h2>
       <div class="api-groups">
         <div v-for="item of section.items" :key="item.text" class="api-group">
-          <h3>{{ item.text }}</h3>
+          <h3>
+            <a :href="item.link + '.html'">{{ item.text }}</a>
+          </h3>
           <ul>
             <li v-for="h of item.headers" :key="h.anchor">
               <a :href="item.link + '.html#' + slugify(h.anchor)">{{
@@ -158,7 +160,7 @@ h3 {
   margin-bottom: 64px;
 }
 
-.api-groups a {
+.api-groups ul a {
   font-size: 15px;
   font-weight: 500;
   line-height: 2;
@@ -166,11 +168,11 @@ h3 {
   transition: color 0.5s;
 }
 
-.dark .api-groups a {
+.dark .api-groups ul a {
   font-weight: 400;
 }
 
-.api-groups a:hover {
+.api-groups ul a:hover {
   color: var(--vp-c-green);
   transition: none;
 }
@@ -233,7 +235,7 @@ h3 {
     padding-top: 32px;
   }
 
-  .api-groups a {
+  .api-groups ul a {
     font-size: 14px;
   }
 
diff --git a/scripts/apidoc/moduleMethods.ts b/scripts/apidoc/moduleMethods.ts
index b89e873c..cdd9222e 100644
--- a/scripts/apidoc/moduleMethods.ts
+++ b/scripts/apidoc/moduleMethods.ts
@@ -1,7 +1,7 @@
 import type { DeclarationReflection, ProjectReflection } from 'typedoc';
 import type { Method } from '../../docs/.vitepress/components/api-docs/method';
 import { writeApiDocsData, writeApiDocsModulePage } from './apiDocsWriter';
-import { analyzeSignature, toBlock } from './signature';
+import { analyzeSignature, stripAbsoluteFakerUrls, toBlock } from './signature';
 import {
   extractModuleFieldName,
   extractModuleName,
@@ -40,7 +40,7 @@ function processModuleMethod(module: DeclarationReflection): PageAndDiffIndex {
   const moduleName = extractModuleName(module);
   const moduleFieldName = extractModuleFieldName(module);
   console.log(`Processing Module ${moduleName}`);
-  const comment = toBlock(module.comment);
+  const comment = stripAbsoluteFakerUrls(toBlock(module.comment));
 
   const methods: Method[] = [];
 
diff --git a/scripts/apidoc/signature.ts b/scripts/apidoc/signature.ts
index c41b758c..b3bd4523 100644
--- a/scripts/apidoc/signature.ts
+++ b/scripts/apidoc/signature.ts
@@ -44,6 +44,10 @@ export function toBlock(comment?: Comment): string {
   return joinTagParts(comment?.summary) || 'Missing';
 }
 
+export function stripAbsoluteFakerUrls(markdown: string): string {
+  return markdown.replace(/https:\/\/(next.)?fakerjs.dev\//g, '/');
+}
+
 let markdown: MarkdownRenderer;
 
 export async function initMarkdownRenderer(): Promise<void> {
diff --git a/src/modules/airline/index.ts b/src/modules/airline/index.ts
index 14653bc8..a9432dc6 100644
--- a/src/modules/airline/index.ts
+++ b/src/modules/airline/index.ts
@@ -61,7 +61,21 @@ const aircraftTypeSeats: Record<AircraftType, string[]> = {
 };
 
 /**
- * Module to generate airline related data.
+ * Module to generate airline and airport related data.
+ *
+ * ### Overview
+ *
+ * Several methods in this module return objects rather than strings. For example, you can use `faker.airline.airport().iataCode` to pick out the specific property you need.
+ *
+ * For a random airport, use [`airport()`](https://next.fakerjs.dev/api/airline.html#airport).
+ *
+ * For a random airline, use [`airline()`](https://next.fakerjs.dev/api/airline.html#airline).
+ *
+ * For a dummy booking, a passenger will generally book a flight on a specific [`flightNumber()`](https://next.fakerjs.dev/api/airline.html#flightnumber), [`airplane()`](https://next.fakerjs.dev/api/airline.html#airplane), be allocated a [`seat()`](https://next.fakerjs.dev/api/airline.html#seat), and [`recordLocator()`](https://next.fakerjs.dev/api/airline.html#recordlocator).
+ *
+ * ### Related Modules
+ *
+ * - To generate sample passenger data, you can use the methods of the [`faker.person`](https://next.fakerjs.dev/api/person.html) module.
  */
 export class AirlineModule {
   constructor(private readonly faker: Faker) {
diff --git a/src/modules/animal/index.ts b/src/modules/animal/index.ts
index 90efc7ab..9442839f 100644
--- a/src/modules/animal/index.ts
+++ b/src/modules/animal/index.ts
@@ -2,6 +2,14 @@ import type { Faker } from '../..';
 
 /**
  * Module to generate animal related entries.
+ *
+ * ### Overview
+ *
+ * For a general type of animal (e.g. `'dog'`), use [`type()`](https://next.fakerjs.dev/api/animal.html#type).
+ *
+ * Otherwise, use one of the more specific methods, such as [`cat()`](https://next.fakerjs.dev/api/animal.html#cat) for a specific breed of cat.
+ *
+ * All values may be localized.
  */
 export class AnimalModule {
   constructor(private readonly faker: Faker) {
diff --git a/src/modules/color/index.ts b/src/modules/color/index.ts
index 651716f0..5e4582df 100644
--- a/src/modules/color/index.ts
+++ b/src/modules/color/index.ts
@@ -163,6 +163,12 @@ function toColorFormat(
 
 /**
  * Module to generate colors.
+ *
+ * ### Overview
+ *
+ * For a human-readable color like `'red'`, use [`human()`](https://next.fakerjs.dev/api/color.html#human).
+ *
+ * For a hex color like `#ff0000` used in HTML/CSS, use [`rgb()`](https://next.fakerjs.dev/api/color.html#rgb). There are also methods for other color formats such as [`hsl()`](https://next.fakerjs.dev/api/color.html#hsl), [`cmyk()`](https://next.fakerjs.dev/api/color.html#cmyk), [`hwb()`](https://next.fakerjs.dev/api/color.html#hwb), [`lab()`](https://next.fakerjs.dev/api/color.html#lab), and [`lch()`](https://next.fakerjs.dev/api/color.html#lch).
  */
 export class ColorModule {
   constructor(private readonly faker: Faker) {
diff --git a/src/modules/commerce/index.ts b/src/modules/commerce/index.ts
index 54d2bce1..ffb602b0 100644
--- a/src/modules/commerce/index.ts
+++ b/src/modules/commerce/index.ts
@@ -3,6 +3,14 @@ import { deprecated } from '../../internal/deprecated';
 
 /**
  * Module to generate commerce and product related entries.
+ *
+ * ### Overview
+ *
+ * For a long product name like `'Incredible Soft Gloves'`, use [`productName()`](https://next.fakerjs.dev/api/commerce.html#productname). The product names are generated from a list of adjectives, materials, and products, which can each be accessed separately using [`productAdjective()`](https://next.fakerjs.dev/api/commerce.html#productadjective), [`productMaterial()`](https://next.fakerjs.dev/api/commerce.html#productmaterial), and [`product()`](https://next.fakerjs.dev/api/commerce.html#product). You can also create a description using [`productDescription()`](https://next.fakerjs.dev/api/commerce.html#productdescription).
+ *
+ * For a department in a shop or product category, use [`department()`](https://next.fakerjs.dev/api/commerce.html#department).
+ *
+ * You can also create a price using [`price()`](https://next.fakerjs.dev/api/commerce.html#price).
  */
 export class CommerceModule {
   constructor(private readonly faker: Faker) {
diff --git a/src/modules/company/index.ts b/src/modules/company/index.ts
index 2ced10e9..98dc2c68 100644
--- a/src/modules/company/index.ts
+++ b/src/modules/company/index.ts
@@ -3,6 +3,17 @@ import { deprecated } from '../../internal/deprecated';
 
 /**
  * Module to generate company related entries.
+ *
+ * ### Overview
+ *
+ * To generate a random company name, use [`name()`](https://next.fakerjs.dev/api/company.html#name). This is localized in many locales.
+ *
+ * To generate jargon-filled company catchphrases and buzzwords, use [`catchPhrase()`](https://next.fakerjs.dev/api/company.html#catchphrase) or [`buzzPhrase()`](https://next.fakerjs.dev/api/company.html#buzzphrase).
+ *
+ * ### Related Modules
+ *
+ * - For products and commerce, use [`faker.commerce`](https://next.fakerjs.dev/api/commerce.html).
+ * - For finance-related entries, use [`faker.finance`](https://next.fakerjs.dev/api/finance.html).
  */
 export class CompanyModule {
   constructor(private readonly faker: Faker) {
diff --git a/src/modules/database/index.ts b/src/modules/database/index.ts
index 88a7609a..5f497721 100644
--- a/src/modules/database/index.ts
+++ b/src/modules/database/index.ts
@@ -2,6 +2,12 @@ import type { Faker } from '../..';
 
 /**
  * Module to generate database related entries.
+ *
+ * ### Overview
+ *
+ * Traditional relational database tables have data organized in columns with specific types - [`column()`](https://next.fakerjs.dev/api/database.html#column), [`type()`](https://next.fakerjs.dev/api/database.html#type). The database usually has an [`engine()`](https://next.fakerjs.dev/api/database.html#engine) and a default [`collation()`](https://next.fakerjs.dev/api/database.html#collation) for sorting.
+ *
+ * For the NoSQL database MongoDB, [`mongodbObjectId()`](https://next.fakerjs.dev/api/database.html#mongodbobjectid) provides a random ID.
  */
 export class DatabaseModule {
   constructor(private readonly faker: Faker) {
diff --git a/src/modules/datatype/index.ts b/src/modules/datatype/index.ts
index 540c4ab5..7e5946d8 100644
--- a/src/modules/datatype/index.ts
+++ b/src/modules/datatype/index.ts
@@ -3,6 +3,12 @@ import { deprecated } from '../../internal/deprecated';
 
 /**
  * Module to generate various primitive values and data types.
+ *
+ * ### Overview
+ *
+ * Most of the methods in this module are deprecated and have been moved to other modules like [`faker.number`](https://next.fakerjs.dev/api/number.html) and [`faker.string`](https://next.fakerjs.dev/api/string.html), see individual entries for replacements.
+ *
+ * For a simple random true or false value, use [`boolean()`](https://next.fakerjs.dev/api/datatype.html#boolean).
  */
 export class DatatypeModule {
   constructor(private readonly faker: Faker) {
diff --git a/src/modules/date/index.ts b/src/modules/date/index.ts
index 7156bf22..76987735 100644
--- a/src/modules/date/index.ts
+++ b/src/modules/date/index.ts
@@ -24,6 +24,18 @@ function toDate(
 
 /**
  * Module to generate dates.
+ *
+ * ### Overview
+ *
+ * To quickly generate a date in the past, use [`recent()`](https://next.fakerjs.dev/api/date.html#recent) (last day) or [`past()`](https://next.fakerjs.dev/api/date.html#past) (last year).
+ * To quickly generate a date in the future, use [`soon()`](https://next.fakerjs.dev/api/date.html#soon) (next day) or [`future()`](https://next.fakerjs.dev/api/date.html#future) (next year).
+ * For a realistic birthdate for an adult, use [`birthdate()`](https://next.fakerjs.dev/api/date.html#birthdate).
+ *
+ * For more control, any of these methods can be customized with further options, or use [`between()`](https://next.fakerjs.dev/api/date.html#between) to generate a single date between two dates, or [`betweens()`](https://next.fakerjs.dev/api/date.html#betweens) for multiple dates.
+ *
+ * You can generate random localized month and weekday names using [`month()`](https://next.fakerjs.dev/api/date.html#month) and [`weekday()`](https://next.fakerjs.dev/api/date.html#weekday).
+ *
+ * These methods have additional concerns about reproducibility, see [Reproducible Results](https://next.fakerjs.dev/guide/usage.html#reproducible-results).
  */
 export class DateModule {
   constructor(private readonly faker: Faker) {
diff --git a/src/modules/finance/index.ts b/src/modules/finance/index.ts
index 84b42077..208bfacf 100644
--- a/src/modules/finance/index.ts
+++ b/src/modules/finance/index.ts
@@ -23,7 +23,17 @@ export interface Currency {
 }
 
 /**
- * Module to generate finance related entries.
+ * Module to generate finance and money related entries.
+ *
+ * ### Overview
+ *
+ * For a random amount, use [`amount()`](https://next.fakerjs.dev/api/finance.html#amount).
+ *
+ * For traditional bank accounts, use: [`account()`](https://next.fakerjs.dev/api/finance.html#account), [`accountName()`](https://next.fakerjs.dev/api/finance.html#accountname), [`bic()`](https://next.fakerjs.dev/api/finance.html#bic), [`iban()`](https://next.fakerjs.dev/api/finance.html#iban), [`pin()`](https://next.fakerjs.dev/api/finance.html#pin) and [`routingNumber()`](https://next.fakerjs.dev/api/finance.html#routingnumber).
+ *
+ * For credit card related methods, use: [`creditCardNumber()`](https://next.fakerjs.dev/api/finance.html#creditcardnumber), [`creditCardCVV()`](https://next.fakerjs.dev/api/finance.html#creditcardcvv), [`creditCardIssuer()`](https://next.fakerjs.dev/api/finance.html#creditcardissuer), [`transactionDescription()`](https://next.fakerjs.dev/api/finance.html#transactiondescription) and [`transactionType()`](https://next.fakerjs.dev/api/finance.html#transactiontype).
+ *
+ * For blockchain related methods, use: [`bitcoinAddress()`](https://next.fakerjs.dev/api/finance.html#bitcoinaddress), [`ethereumAddress()`](https://next.fakerjs.dev/api/finance.html#ethereumaddress) and [`litecoinAddress()`](https://next.fakerjs.dev/api/finance.html#litecoinaddress).
  */
 export class FinanceModule {
   constructor(private readonly faker: Faker) {
diff --git a/src/modules/git/index.ts b/src/modules/git/index.ts
index e35ece2b..81e79af0 100644
--- a/src/modules/git/index.ts
+++ b/src/modules/git/index.ts
@@ -21,6 +21,10 @@ const GIT_TIMEZONE_FORMAT = new Intl.NumberFormat('en', {
 
 /**
  * Module to generate git related entries.
+ *
+ * ### Overview
+ *
+ * [`commitEntry()`](https://next.fakerjs.dev/api/git.html#commitentry) generates a random commit entry as printed by `git log`. This includes a commit hash [`commitSha()`](https://next.fakerjs.dev/api/git.html#commitsha), author, date [`commitDate()`](https://next.fakerjs.dev/api/git.html#commitdate), and commit message [`commitMessage()`](https://next.fakerjs.dev/api/git.html#commitmessage). You can also generate a random branch name with [`branch()`](https://next.fakerjs.dev/api/git.html#branch).
  */
 export class GitModule {
   constructor(private readonly faker: Faker) {
diff --git a/src/modules/hacker/index.ts b/src/modules/hacker/index.ts
index 00b9a686..ef0aa013 100644
--- a/src/modules/hacker/index.ts
+++ b/src/modules/hacker/index.ts
@@ -2,6 +2,18 @@ import type { Faker } from '../..';
 
 /**
  * Module to generate hacker/IT words and phrases.
+ *
+ * ### Overview
+ *
+ * There are methods for different parts of speech, such as [`abbreviation()`](https://next.fakerjs.dev/api/hacker.html#abbreviation), [`adjective()`](https://next.fakerjs.dev/api/hacker.html#adjective), [`noun()`](https://next.fakerjs.dev/api/hacker.html#noun), [`verb()`](https://next.fakerjs.dev/api/hacker.html#verb), and [`ingverb()`](https://next.fakerjs.dev/api/hacker.html#ingverb). Alternatively, [`phrase()`](https://next.fakerjs.dev/api/hacker.html#phrase) creates a longer phrase combining these words.
+ *
+ * ### Related modules
+ *
+ * Various modules allow for generating other types of words and phrases:
+ *
+ * - [faker.word](https://next.fakerjs.dev/api/word.html) uses general vocabulary rather than hacker-specific terms.
+ * - [faker.lorem](https://next.fakerjs.dev/api/lorem.html) uses faux-Latin "lorem ipsum" text.
+ * - [faker.company](https://next.fakerjs.dev/api/company.html) includes corporate catchphrases and buzzwords.
  */
 export class HackerModule {
   constructor(private readonly faker: Faker) {
diff --git a/src/modules/helpers/index.ts b/src/modules/helpers/index.ts
index 6cc19863..1b9b5282 100644
--- a/src/modules/helpers/index.ts
+++ b/src/modules/helpers/index.ts
@@ -72,6 +72,14 @@ function getRepetitionsBasedOnQuantifierParameters(
 
 /**
  * Module with various helper methods providing basic (seed-dependent) operations useful for implementing faker methods.
+ *
+ * ### Overview
+ *
+ * A particularly helpful method is [`arrayElement()`](https://next.fakerjs.dev/api/helpers.html#arrayelement) which returns a random element from an array. This is useful when adding custom data that Faker doesn't contain.
+ *
+ * There are alternatives of this method for objects ([`objectKey()`](https://next.fakerjs.dev/api/helpers.html#objectkey) and [`objectValue()`](https://next.fakerjs.dev/api/helpers.html#objectvalue)) and enums ([`enumValue()`](https://next.fakerjs.dev/api/helpers.html#enumvalue)). You can also return multiple elements ([`arrayElements()`](https://next.fakerjs.dev/api/helpers.html#arrayelements)) or elements according to a weighting ([`weightedArrayElement()`](https://next.fakerjs.dev/api/helpers.html#weightedarrayelement)).
+ *
+ * A number of methods can generate strings according to various patterns: [`replaceSymbols()`](https://next.fakerjs.dev/api/helpers.html#replacesymbols), [`replaceSymbolWithNumber()`](https://next.fakerjs.dev/api/helpers.html#replacesymbolwithnumber), and [`fromRegExp()`](https://next.fakerjs.dev/api/helpers.html#fromregexp).
  */
 export class HelpersModule {
   constructor(private readonly faker: Faker) {
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 {
   /**
diff --git a/src/modules/internet/index.ts b/src/modules/internet/index.ts
index 3502f85b..066044aa 100644
--- a/src/modules/internet/index.ts
+++ b/src/modules/internet/index.ts
@@ -26,6 +26,16 @@ export type HTTPProtocolType = 'http' | 'https';
 
 /**
  * Module to generate internet related entries.
+ *
+ * ### Overview
+ *
+ * For user accounts, you may need an [`email()`](https://next.fakerjs.dev/api/internet.html#email) and a [`password()`](https://next.fakerjs.dev/api/internet.html#password), as well as a ASCII [`userName()`](https://next.fakerjs.dev/api/internet.html#username) or Unicode [`displayName()`](https://next.fakerjs.dev/api/internet.html#displayname), and an image [`avatar()`](https://next.fakerjs.dev/api/internet.html#avatar). Since the emails generated could coincidentally be real email addresses, you should not use these for sending real email addresses. If this is a concern, use [`exampleEmail()`](https://next.fakerjs.dev/api/internet.html#exampleemail) instead.
+ *
+ * For websites, you can generate a [`domainName()`](https://next.fakerjs.dev/api/internet.html#domainname) or a full [`url()`](https://next.fakerjs.dev/api/internet.html#url).
+ *
+ * To make your data more 🔥, you can use [`emoji()`](https://next.fakerjs.dev/api/internet.html#emoji).
+ *
+ * You also have access to a number of the more technical elements of web requests, such as [`httpMethod`](https://next.fakerjs.dev/api/internet.html#httpmethod), [`httpStatusCode`](https://next.fakerjs.dev/api/internet.html#httpstatuscode), [`ip`](https://next.fakerjs.dev/api/internet.html#ip), [`mac`](https://next.fakerjs.dev/api/internet.html#mac), [`userAgent`](https://next.fakerjs.dev/api/internet.html#useragent), and [`port`](https://next.fakerjs.dev/api/internet.html#port).
  */
 export class InternetModule {
   constructor(private readonly faker: Faker) {
diff --git a/src/modules/location/index.ts b/src/modules/location/index.ts
index 37d8f14f..ab158ecb 100644
--- a/src/modules/location/index.ts
+++ b/src/modules/location/index.ts
@@ -2,7 +2,15 @@ import type { Faker } from '../..';
 import { deprecated } from '../../internal/deprecated';
 
 /**
- * Module to generate addresses and locations.
+ * Module to generate addresses and locations. Prior to Faker 8.0.0, this module was known as `faker.address`.
+ *
+ * ### Overview
+ *
+ * For a typical street address for a locale, use [`streetAddress()`](https://next.fakerjs.dev/api/location.html#streetaddress), [`city()`](https://next.fakerjs.dev/api/location.html#city), [`state()`](https://next.fakerjs.dev/api/location.html#state) (or [`stateAbbr()`](https://next.fakerjs.dev/api/location.html#stateabbr)), and [`zipCode()`](https://next.fakerjs.dev/api/location.html#zipcode). Most locales provide localized versions for a specific country.
+ *
+ * If you need latitude and longitude coordinates, use [`latitude()`](https://next.fakerjs.dev/api/location.html#latitude) and [`longitude()`](https://next.fakerjs.dev/api/location.html#longitude), or [`nearbyGPSCoordinate()`](https://next.fakerjs.dev/api/location.html#nearbygpscoordinate) for a latitude/longitude near a given location.
+ *
+ * For a random country, you can use [`country()`](https://next.fakerjs.dev/api/location.html#country) or [`countryCode()`](https://next.fakerjs.dev/api/location.html#countrycode).
  */
 export class LocationModule {
   constructor(private readonly faker: Faker) {
diff --git a/src/modules/lorem/index.ts b/src/modules/lorem/index.ts
index 4e124929..fb633a0d 100644
--- a/src/modules/lorem/index.ts
+++ b/src/modules/lorem/index.ts
@@ -3,6 +3,14 @@ import { filterWordListByLength } from '../word/filterWordListByLength';
 
 /**
  * Module to generate random texts and words.
+ *
+ * ### Overview
+ *
+ * Generate dummy content using traditional faux-Latin [lorem ipsum](https://en.wikipedia.org/wiki/Lorem_ipsum) (in other locales to `en`, alternative words may be used).
+ *
+ * In order of increasing size you can generate a single [`word()`](https://next.fakerjs.dev/api/lorem.html#word), multiple [`words()`](https://next.fakerjs.dev/api/lorem.html#words), a [`sentence()`](https://next.fakerjs.dev/api/lorem.html#sentence), multiple [`sentences()`](https://next.fakerjs.dev/api/lorem.html#sentences), [`lines()`](https://next.fakerjs.dev/api/lorem.html#lines) separated by newlines, one [`paragraph()`](https://next.fakerjs.dev/api/lorem.html#paragraph), or multiple [`paragraphs()`](https://next.fakerjs.dev/api/lorem.html#paragraphs).
+ *
+ * The generic [`text()`](https://next.fakerjs.dev/api/lorem.html#text) method can be used to generate some text between one sentence and multiple paragraphs, while [`slug()`](https://next.fakerjs.dev/api/lorem.html#slug) generates an URL-friendly hyphenated string.
  */
 export class LoremModule {
   constructor(private readonly faker: Faker) {
diff --git a/src/modules/music/index.ts b/src/modules/music/index.ts
index 15d282d4..65faf452 100644
--- a/src/modules/music/index.ts
+++ b/src/modules/music/index.ts
@@ -2,6 +2,10 @@ import type { Faker } from '../..';
 
 /**
  * Module to generate music related entries.
+ *
+ * ### Overview
+ *
+ * Generate a random music genre with [`genre()`](https://next.fakerjs.dev/api/music.html#genre) or song name with [`songName()`](https://next.fakerjs.dev/api/music.html#songname). Both may be localized.
  */
 export class MusicModule {
   constructor(private readonly faker: Faker) {
diff --git a/src/modules/number/index.ts b/src/modules/number/index.ts
index 3cd35f40..1e3ed363 100644
--- a/src/modules/number/index.ts
+++ b/src/modules/number/index.ts
@@ -4,6 +4,17 @@ import type { Mersenne } from '../../internal/mersenne/mersenne';
 
 /**
  * Module to generate numbers of any kind.
+ *
+ * ### Overview
+ *
+ * For simple integers, use [`int()`](https://next.fakerjs.dev/api/number.html#int). For decimal/floating-point numbers, use [`float()`](https://next.fakerjs.dev/api/number.html#float).
+ *
+ * For numbers not in base-10, you can use [`hex()`](https://next.fakerjs.dev/api/number.html#hex), [`octal()`](https://next.fakerjs.dev/api/number.html#octal) and [`binary()`](https://next.fakerjs.dev/api/number.html#binary)`.
+ *
+ * ### Related modules
+ *
+ * - For numeric strings of a given length, use [`faker.string.numeric()`](https://next.fakerjs.dev/api/string.html#numeric).
+ * - For credit card numbers, use [`faker.finance.creditCardNumber()`](https://next.fakerjs.dev/api/finance.html#creditcardnumber).
  */
 export class NumberModule {
   constructor(private readonly faker: Faker) {
diff --git a/src/modules/person/index.ts b/src/modules/person/index.ts
index d7d2d3c9..b1722bc0 100644
--- a/src/modules/person/index.ts
+++ b/src/modules/person/index.ts
@@ -54,7 +54,24 @@ function selectDefinition<T>(
 }
 
 /**
- * Module to generate people's names and titles.
+ * Module to generate people's personal information such as names and job titles. Prior to Faker 8.0.0, this module was known as `faker.name`.
+ *
+ * ### Overview
+ * 
+ * To generate a full name, use [`fullName`](https://next.fakerjs.dev/api/person.html#fullname). Note that this is not the same as simply concatenating [`firstName`](https://next.fakerjs.dev/api/person.html#firstname) and [`lastName`](https://next.fakerjs.dev/api/person.html#lastname), as the full name may contain a prefix, suffix, or both. Additionally, different supported locales will have differing name patterns. For example, the last name may appear before the first name, or there may be a double or hyphenated first or last name.
+ * 
+ * You can also generate the parts of a name separately, using [`prefix`](https://next.fakerjs.dev/api/person.html#prefix), [`firstName`](https://next.fakerjs.dev/api/person.html#firstname), [`middleName`](https://next.fakerjs.dev/api/person.html#middlename), [`lastName`](https://next.fakerjs.dev/api/person.html#lastname), and [`suffix`](https://next.fakerjs.dev/api/person.html#suffix). Not all locales support all of these parts.
+ *
+ * Many of the methods in this module can optionally choose either female, male or mixed names.
+ *
+ * Job-related data is also available. To generate a job title, use [`jobTitle`](https://next.fakerjs.dev/api/person.html#jobtitle). 
+ * 
+ * This module can also generate other personal information which might appear in user profiles, such as [`gender`](https://next.fakerjs.dev/api/person.html#gender), [`zodiacSign`](https://next.fakerjs.dev/api/person.html#zodiacsign), and [`bio`](https://next.fakerjs.dev/api/person.html#bio).
+ * 
+ * ### Related modules
+ *
+ * For personal contact information like phone numbers and email addresses, see the [`faker.phone`](https://next.fakerjs.dev/api/phone.html) and [`faker.internet`](https://next.fakerjs.dev/api/internet.html) modules.
+ 
  */
 export class PersonModule {
   constructor(private readonly faker: Faker) {
diff --git a/src/modules/phone/index.ts b/src/modules/phone/index.ts
index d604c44a..a9254650 100644
--- a/src/modules/phone/index.ts
+++ b/src/modules/phone/index.ts
@@ -2,6 +2,10 @@ import type { Faker } from '../..';
 
 /**
  * Module to generate phone-related data.
+ *
+ * ### Overview
+ *
+ * For a phone number, use [`number()`](https://next.fakerjs.dev/api/phone.html#number). Many locales provide country-specific formats.
  */
 export class PhoneModule {
   constructor(private readonly faker: Faker) {
diff --git a/src/modules/random/index.ts b/src/modules/random/index.ts
index 2a44b0e2..df58d292 100644
--- a/src/modules/random/index.ts
+++ b/src/modules/random/index.ts
@@ -12,6 +12,10 @@ import type {
 /**
  * Generates random values of different kinds.
  *
+ * ### Overview
+ *
+ * All the methods in this module are deprecated.
+ *
  * @deprecated Use the modules specific to the type of data you want to generate instead.
  */
 export class RandomModule {
diff --git a/src/modules/science/index.ts b/src/modules/science/index.ts
index 754bcbdf..ef85f299 100644
--- a/src/modules/science/index.ts
+++ b/src/modules/science/index.ts
@@ -31,6 +31,10 @@ export interface Unit {
 
 /**
  * Module to generate science related entries.
+ *
+ * ### Overview
+ *
+ * Both methods in this module return objects rather than strings. For example, you can use `faker.science.chemicalElement().name` to pick out the specific property you need.
  */
 export class ScienceModule {
   constructor(private readonly faker: Faker) {
diff --git a/src/modules/string/index.ts b/src/modules/string/index.ts
index f6180df3..4c5a7dc3 100644
--- a/src/modules/string/index.ts
+++ b/src/modules/string/index.ts
@@ -87,6 +87,19 @@ const SAMPLE_MAX_LENGTH = 2 ** 20;
 
 /**
  * Module to generate string related entries.
+ *
+ * ### Overview
+ *
+ * For a string containing just A-Z characters, use [`alpha()`](https://next.fakerjs.dev/api/string.html#alpha). To add digits too, use [`alphanumeric()`](https://next.fakerjs.dev/api/string.html#alphanumeric). If you only want punctuation marks/symbols, use [`symbol()`](https://next.fakerjs.dev/api/string.html). For a full set of ASCII characters, use [`sample()`](https://next.fakerjs.dev/api/string.html#sample). For a custom set of characters, use [`fromCharacters()`](https://next.fakerjs.dev/api/string.html#fromcharacters).
+ *
+ * For strings of base-ten digits, use [`numeric()`](https://next.fakerjs.dev/api/string.html#numeric). For other bases, use [`binary()`](https://next.fakerjs.dev/api/string.html#binary), [`octal()`](https://next.fakerjs.dev/api/string.html#octal), or [`hexadecimal()`](https://next.fakerjs.dev/api/string.html#hexadecimal)).
+ *
+ * You can generate standard ID strings using [`uuid()`](https://next.fakerjs.dev/api/string.html#uuid) or [`nanoid()`](https://next.fakerjs.dev/api/string.html#nanoid).
+ *
+ * ### Related modules
+ *
+ * - Emoji can be found at [`faker.internet.emoji()`](https://next.fakerjs.dev/api/internet.html#emoji).
+ * - The [`faker.helpers`](https://next.fakerjs.dev/api/helpers.html) module includes a number of string related methods.
  */
 export class StringModule {
   constructor(private readonly faker: Faker) {
diff --git a/src/modules/vehicle/index.ts b/src/modules/vehicle/index.ts
index 2b153c79..25308dcb 100644
--- a/src/modules/vehicle/index.ts
+++ b/src/modules/vehicle/index.ts
@@ -2,6 +2,12 @@ import type { Faker } from '../..';
 
 /**
  * Module to generate vehicle related entries.
+ *
+ * ### Overview
+ *
+ * Most methods are related to cars/automobiles: a [`vehicle()`](https://next.fakerjs.dev/api/vehicle.html#vehicle) name is comprised of a car [`manufacturer()`](https://next.fakerjs.dev/api/vehicle.html#manufacturer) and [`model()`](https://next.fakerjs.dev/api/vehicle.html#model). You can also generate [`fuel()`](https://next.fakerjs.dev/api/vehicle.html#fuel), [`type()`](https://next.fakerjs.dev/api/vehicle.html#type), and [`color()`](https://next.fakerjs.dev/api/vehicle.html#color), as well as typical car registration IDs [`vin()`](https://next.fakerjs.dev/api/vehicle.html#vin) and [`vrm()`](https://next.fakerjs.dev/api/vehicle.html#vrm).
+ *
+ * If you prefer two wheels, you can generate a [`bicycle()`](https://next.fakerjs.dev/api/vehicle.html#bicycle) type instead.
  */
 export class VehicleModule {
   constructor(private readonly faker: Faker) {
-- 
cgit v1.2.3