Merge branch 'next' into refactor/location/merge-state-and-state-abbr

docs/.vitepress/components/api-docs/method.ts

@@ -8,6 +8,7 @@ export interface Method {
   readonly since: string;
   readonly sourcePath: string; // URL-Suffix
   readonly seeAlsos: string[];
+  readonly throws?: string; // HTML
 }
 
 export interface MethodParameter {

docs/.vitepress/components/api-docs/method.vue

@@ -36,6 +36,10 @@ function seeAlsoToUrl(see: string): string {
 
     <p><strong>Returns:</strong> {{ props.method.returns }}</p>
 
+    <p v-if="props.method.throws">
+      <strong>Throws:</strong> <span v-html="props.method.throws" />
+    </p>
+
     <div v-html="props.method.examples" />
 
     <div v-if="props.method.seeAlsos.length > 0">

scripts/apidoc/signature.ts

@@ -25,6 +25,7 @@ import {
   extractSeeAlsos,
   extractSince,
   extractSourcePath,
+  extractThrows,
   joinTagParts,
 } from './typedoc';
 import { pathOutputDir } from './utils';
@@ -160,12 +161,16 @@ export function analyzeSignature(
   const deprecated = deprecatedMessage
     ? mdToHtml(deprecatedMessage)
     : undefined;
+  const throwsMessage = extractThrows(signature);
+  const throws = throwsMessage ? mdToHtml(throwsMessage, true) : undefined;
+
   return {
     name: methodName,
     description: mdToHtml(toBlock(signature.comment)),
     parameters: parameters,
     since: extractSince(signature),
     sourcePath: extractSourcePath(signature),
+    throws,
     returns: typeToText(signature.type),
     examples: mdToHtml(`${code}ts\n${examples}${code}`),
     deprecated,

scripts/apidoc/typedoc.ts

@@ -286,6 +286,18 @@ export function extractDeprecated(
   return deprecated.length === 0 ? undefined : deprecated;
 }
 
+/**
+ * Extracts the "throws" tag from the provided signature.
+ *
+ * @param reflection The reflection to check.
+ *
+ * @returns The message explaining the conditions when this method throws. Or `undefined` if it does not throw.
+ */
+export function extractThrows(reflection?: CommentHolder): string | undefined {
+  const throws = extractTagContent('@throws', reflection).join().trim();
+  return throws.length === 0 ? undefined : throws;
+}
+
 /**
  * Extracts the "since" tag from the provided signature.
  *

scripts/generateLocales.ts

@@ -126,7 +126,7 @@ function generateLocaleFile(locale: string): void {
     }
   }
 
-  // TODO christopher 2023-03-07: Remove 'en' fallback in a separate PR
+  // TODO @Shinigami92 2023-03-07: Remove 'en' fallback in a separate PR
   if (locales[locales.length - 1] !== 'en' && locale !== 'base') {
     locales.push('en');
   }

src/definitions/company.ts

@@ -32,7 +32,7 @@ export type CompanyDefinitions = LocaleEntry<{
   /**
    * A list of patterns used to generate company names.
    */
-  name_patterns: string[];
+  name_pattern: string[];
 
   /**
    * Catchphrase nouns that can be displayed to an end user.

src/definitions/person.ts

@@ -33,11 +33,11 @@ export type PersonDefinitions = LocaleEntry<{
   /**
    * A weighted list of patterns used to generate last names.
    */
-  last_name_patterns?: Array<{ value: string; weight: number }>;
-  male_last_name_patterns?: Array<{ value: string; weight: number }>;
-  female_last_name_patterns?: Array<{ value: string; weight: number }>;
+  last_name_pattern?: Array<{ value: string; weight: number }>;
+  male_last_name_pattern?: Array<{ value: string; weight: number }>;
+  female_last_name_pattern?: Array<{ value: string; weight: number }>;
 
-  bio_patterns?: string[];
+  bio_pattern?: string[];
 
   title: PersonTitleDefinitions;
 

src/faker.ts

@@ -46,7 +46,6 @@ import { mergeLocales } from './utils/merge-locales';
  *
  * faker.person.firstName(); // 'John'
  * faker.person.lastName(); // 'Doe'
- *
  * @example
  * import { Faker, es } from '@faker-js/faker';
  * // const { Faker, es } = require('@faker-js/faker');
@@ -347,6 +346,7 @@ export class Faker {
    * by logging the result and explicitly setting it if needed.
    *
    * @param seed The seed to use. Defaults to a random number.
+   *
    * @returns The seed that was set.
    *
    * @see [Reproducible Results](https://next.fakerjs.dev/guide/usage.html#reproducible-results)
@@ -381,6 +381,7 @@ export class Faker {
    * by logging the result and explicitly setting it if needed.
    *
    * @param seedArray The seed array to use.
+   *
    * @returns The seed array that was set.
    *
    * @see [Reproducible Results](https://next.fakerjs.dev/guide/usage.html#reproducible-results)
@@ -415,6 +416,7 @@ export class Faker {
    * by logging the result and explicitly setting it if needed.
    *
    * @param seed The seed or seed array to use.
+   *
    * @returns The seed that was set.
    *
    * @see [Reproducible Results](https://next.fakerjs.dev/guide/usage.html#reproducible-results)

src/locales/af_ZA/person/index.ts

@@ -6,14 +6,14 @@ import type { PersonDefinitions } from '../../..';
 import female_first_name from './female_first_name';
 import first_name from './first_name';
 import last_name from './last_name';
-import last_name_patterns from './last_name_patterns';
+import last_name_pattern from './last_name_pattern';
 import male_first_name from './male_first_name';
 
 const person: PersonDefinitions = {
   female_first_name,
   first_name,
   last_name,
-  last_name_patterns,
+  last_name_pattern,
   male_first_name,
 };
 

src/locales/ar/person/index.ts

@@ -7,7 +7,7 @@ import female_first_name from './female_first_name';
 import female_prefix from './female_prefix';
 import first_name from './first_name';
 import last_name from './last_name';
-import last_name_patterns from './last_name_patterns';
+import last_name_pattern from './last_name_pattern';
 import male_first_name from './male_first_name';
 import male_prefix from './male_prefix';
 import name_ from './name';
@@ -20,7 +20,7 @@ const person: PersonDefinitions = {
   female_prefix,
   first_name,
   last_name,
-  last_name_patterns,
+  last_name_pattern,
   male_first_name,
   male_prefix,
   name: name_,

src/locales/az/company/index.ts

@@ -3,12 +3,12 @@
  * Run 'pnpm run generate:locales' to update.
  */
 import type { CompanyDefinitions } from '../../..';
-import name_patterns from './name_patterns';
+import name_pattern from './name_pattern';
 import prefix from './prefix';
 import suffix from './suffix';
 
 const company: CompanyDefinitions = {
-  name_patterns,
+  name_pattern,
   prefix,
   suffix,
 };

src/locales/az/person/index.ts

@@ -5,12 +5,12 @@
 import type { PersonDefinitions } from '../../..';
 import female_first_name from './female_first_name';
 import female_last_name from './female_last_name';
-import female_last_name_patterns from './female_last_name_patterns';
+import female_last_name_pattern from './female_last_name_pattern';
 import female_prefix from './female_prefix';
 import first_name from './first_name';
 import male_first_name from './male_first_name';
 import male_last_name from './male_last_name';
-import male_last_name_patterns from './male_last_name_patterns';
+import male_last_name_pattern from './male_last_name_pattern';
 import male_prefix from './male_prefix';
 import name_ from './name';
 import prefix from './prefix';
@@ -19,12 +19,12 @@ import suffix from './suffix';
 const person: PersonDefinitions = {
   female_first_name,
   female_last_name,
-  female_last_name_patterns,
+  female_last_name_pattern,
   female_prefix,
   first_name,
   male_first_name,
   male_last_name,
-  male_last_name_patterns,
+  male_last_name_pattern,
   male_prefix,
   name: name_,
   prefix,

src/locales/cs_CZ/company/index.ts

@@ -3,11 +3,11 @@
  * Run 'pnpm run generate:locales' to update.
  */
 import type { CompanyDefinitions } from '../../..';
-import name_patterns from './name_patterns';
+import name_pattern from './name_pattern';
 import suffix from './suffix';
 
 const company: CompanyDefinitions = {
-  name_patterns,
+  name_pattern,
   suffix,
 };
 

src/locales/cs_CZ/person/index.ts

@@ -5,13 +5,13 @@
 import type { PersonDefinitions } from '../../..';
 import female_first_name from './female_first_name';
 import female_last_name from './female_last_name';
-import female_last_name_patterns from './female_last_name_patterns';
+import female_last_name_pattern from './female_last_name_pattern';
 import female_prefix from './female_prefix';
 import first_name from './first_name';
 import last_name from './last_name';
 import male_first_name from './male_first_name';
 import male_last_name from './male_last_name';
-import male_last_name_patterns from './male_last_name_patterns';
+import male_last_name_pattern from './male_last_name_pattern';
 import male_prefix from './male_prefix';
 import name_ from './name';
 import prefix from './prefix';
@@ -21,13 +21,13 @@ import title from './title';
 const person: PersonDefinitions = {
   female_first_name,
   female_last_name,
-  female_last_name_patterns,
+  female_last_name_pattern,
   female_prefix,
   first_name,
   last_name,
   male_first_name,
   male_last_name,
-  male_last_name_patterns,
+  male_last_name_pattern,
   male_prefix,
   name: name_,
   prefix,

src/locales/de/company/index.ts

@@ -4,12 +4,12 @@
  */
 import type { CompanyDefinitions } from '../../..';
 import legal_form from './legal_form';
-import name_patterns from './name_patterns';
+import name_pattern from './name_pattern';
 import suffix from './suffix';
 
 const company: CompanyDefinitions = {
   legal_form,
-  name_patterns,
+  name_pattern,
   suffix,
 };
 

src/locales/de/person/index.ts

@@ -7,7 +7,7 @@ import female_first_name from './female_first_name';
 import female_prefix from './female_prefix';
 import first_name from './first_name';
 import last_name from './last_name';
-import last_name_patterns from './last_name_patterns';
+import last_name_pattern from './last_name_pattern';
 import male_first_name from './male_first_name';
 import male_prefix from './male_prefix';
 import name_ from './name';
@@ -20,7 +20,7 @@ const person: PersonDefinitions = {
   female_prefix,
   first_name,
   last_name,
-  last_name_patterns,
+  last_name_pattern,
   male_first_name,
   male_prefix,
   name: name_,

src/locales/de_AT/company/index.ts

@@ -4,12 +4,12 @@
  */
 import type { CompanyDefinitions } from '../../..';
 import legal_form from './legal_form';
-import name_patterns from './name_patterns';
+import name_pattern from './name_pattern';
 import suffix from './suffix';
 
 const company: CompanyDefinitions = {
   legal_form,
-  name_patterns,
+  name_pattern,
   suffix,
 };
 

src/locales/de_AT/person/index.ts

@@ -7,7 +7,7 @@ import female_first_name from './female_first_name';
 import female_prefix from './female_prefix';
 import first_name from './first_name';
 import last_name from './last_name';
-import last_name_patterns from './last_name_patterns';
+import last_name_pattern from './last_name_pattern';
 import male_first_name from './male_first_name';
 import male_prefix from './male_prefix';
 import name_ from './name';
@@ -19,7 +19,7 @@ const person: PersonDefinitions = {
   female_prefix,
   first_name,
   last_name,
-  last_name_patterns,
+  last_name_pattern,
   male_first_name,
   male_prefix,
   name: name_,

src/locales/de_CH/company/index.ts

@@ -3,11 +3,11 @@
  * Run 'pnpm run generate:locales' to update.
  */
 import type { CompanyDefinitions } from '../../..';
-import name_patterns from './name_patterns';
+import name_pattern from './name_pattern';
 import suffix from './suffix';
 
 const company: CompanyDefinitions = {
-  name_patterns,
+  name_pattern,
   suffix,
 };
 

src/locales/de_CH/person/index.ts

@@ -7,7 +7,7 @@ import female_first_name from './female_first_name';
 import female_prefix from './female_prefix';
 import first_name from './first_name';
 import last_name from './last_name';
-import last_name_patterns from './last_name_patterns';
+import last_name_pattern from './last_name_pattern';
 import male_first_name from './male_first_name';
 import male_prefix from './male_prefix';
 import name_ from './name';
@@ -18,7 +18,7 @@ const person: PersonDefinitions = {
   female_prefix,
   first_name,
   last_name,
-  last_name_patterns,
+  last_name_pattern,
   male_first_name,
   male_prefix,
   name: name_,

src/locales/dv/company/index.ts

@@ -4,13 +4,13 @@
  */
 import type { CompanyDefinitions } from '../../..';
 import adjective from './adjective';
-import name_patterns from './name_patterns';
+import name_pattern from './name_pattern';
 import noun from './noun';
 import suffix from './suffix';
 
 const company: CompanyDefinitions = {
   adjective,
-  name_patterns,
+  name_pattern,
   noun,
   suffix,
 };