docs: add overview guides to specific modules

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,19 +160,19 @@ h3 {
   margin-bottom: 64px;
 }
 
-.api-groups a {
+.api-groups ul a {
   font-size: 15px;
   font-weight: 500;
   line-height: 2;
   color: var(--vp-c-text-code);
   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;
   }
 

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[] = [];
 

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> {

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. You can use for example `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
+ *
+ * - For 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) {

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) {

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) {

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 also be accessed seperately 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) {

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) {

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) {

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) {

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 [`birthday()`](https://next.fakerjs.dev/api/date.html#birthday).
+ *
+ * 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](../guide/usage.html#reproducible-results).
  */
 export class DateModule {
   constructor(private readonly faker: Faker) {

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) {

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) {

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), [`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 other 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) {

src/modules/helpers/index.ts

@@ -6,6 +6,14 @@ import * as uniqueExec from './unique';
 
 /**
  * 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 your own custom data which 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 [`regexpStyleStringParse()`](https://next.fakerjs.dev/api/helpers.html#regexpstylestringparse).
  */
 export class HelpersModule {
   constructor(private readonly faker: Faker) {

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 the 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 use your own set of placeholder images.
  */
 export class ImageModule {
   /**

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 use 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 also use [`emoji()`](https://next.fakerjs.dev/api/internet.html#emoji).
+ *
+ * You also have access to a number of 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) {

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) {

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) or [`lines()`](https://next.fakerjs.dev/api/lorem.html#lines) (seperated 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 a 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) {

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) {