docs: improve finance jsdocs (#434)

2 files changed, 84 insertions, 45 deletions

diff --git a/src/definitions/finance.ts b/src/definitions/finance.ts
index afe3639b..859af47a 100644
--- a/src/definitions/finance.ts
+++ b/src/definitions/finance.ts
@@ -9,7 +9,7 @@ export interface FinanceDefinitions {
    */
   account_type: string[];
   /**
-   * The pattern by provider used to generate credit card codes.
+   * The pattern by (lowercase) provider name used to generate credit card codes.
    * `L` will be replaced by the check bit.
    *
    * @see Helpers.replaceCreditCardSymbols()
diff --git a/src/finance.ts b/src/finance.ts
index 7b861758..ece9f7ec 100644
--- a/src/finance.ts
+++ b/src/finance.ts
@@ -2,6 +2,9 @@ import type { Faker } from '.';
 import type { Helpers } from './helpers';
 import ibanLib from './iban';
 
+/**
+ * Module to generate finance related entries.
+ */
 export class Finance {
   readonly ibanLib = ibanLib;
   readonly Helpers: Helpers;
@@ -19,10 +22,13 @@ export class Finance {
   }
 
   /**
-   * account
+   * Generates a random account number.
    *
-   * @method faker.finance.account
-   * @param length
+   * @param length The length of the account number. Defaults to 8.
+   *
+   * @example
+   * faker.finance.account() // 92842238
+   * faker.finance.account(5) // 32564
    */
   account(length?: number): string {
     length = length || 8;
@@ -36,9 +42,10 @@ export class Finance {
   }
 
   /**
-   * accountName
+   * Generates a random account name.
    *
-   * @method faker.finance.accountName
+   * @example
+   * faker.finance.accountName() // 'Personal Loan Account'
    */
   accountName(): string {
     return [
@@ -48,9 +55,10 @@ export class Finance {
   }
 
   /**
-   * routingNumber
+   * Generates a random routing number.
    *
-   * @method faker.finance.routingNumber
+   * @example
+   * faker.finance.routingNumber() // '522814402'
    */
   routingNumber(): string {
     const routingNumber = this.Helpers.replaceSymbolWithNumber('########');
@@ -68,12 +76,17 @@ export class Finance {
   }
 
   /**
-   * mask
+   * Generates a random masked number.
+
+   * @param length The length of the unmasked number. Defaults to `4`.
+   * @param parens Whether to use surrounding parenthesis. Defaults to `true`.
+   * @param ellipsis Whether to prefix the numbers with an ellipsis. Defaults to `true`.
    *
-   * @method faker.finance.mask
-   * @param length
-   * @param parens
-   * @param ellipsis
+   * @example
+   * faker.finance.mask() // '(...9711)'
+   * faker.finance.mask(3) // '(...342)'
+   * faker.finance.mask(3, false) // '...236'
+   * faker.finance.mask(3, false, false) // '298'
    */
   mask(length?: number, parens?: boolean, ellipsis?: boolean): string {
     // set defaults
@@ -104,13 +117,20 @@ export class Finance {
   // NOTE: this returns a string representation of the value, if you want a number use parseFloat and no symbol
 
   /**
-   * amount
+   * Generates a random amount between the given bounds (inclusive).
    *
-   * @method faker.finance.amount
-   * @param min
-   * @param max
-   * @param dec
-   * @param symbol
+   * @param min The lower bound for the amount. Defaults to `0`.
+   * @param max The upper bound for the amount. Defaults to `1000`.
+   * @param dec The number of decimal places for the amount. Defaults to `2`.
+   * @param symbol The symbol used to prefix the amount. Defaults to `''`.
+   * @param autoFormat If true this method will use `Number.toLocaleString()`. Otherwise it will use `Number.toFixed()`.
+   *
+   * @example
+   * faker.finance.amount() // '617.87'
+   * faker.finance.amount(5, 10) // '5.53'
+   * faker.finance.amount(5, 10, 0) // '8'
+   * faker.finance.amount(5, 10, 2, '$') // '$5.85'
+   * faker.finance.amount(5, 10, 5, '', true) // '9,75067'
    */
   amount(
     min: number = 0,
@@ -138,9 +158,10 @@ export class Finance {
   }
 
   /**
-   * transactionType
+   * Returns a random transaction type.
    *
-   * @method faker.finance.transactionType
+   * @example
+   * faker.finance.transactionType() // 'payment'
    */
   transactionType(): string {
     return this.Helpers.randomize(
@@ -149,9 +170,11 @@ export class Finance {
   }
 
   /**
-   * currencyCode
+   * Returns a random currency code.
+   * (The short text/abbreviation for the currency (e.g. `US Dollar` -> `USD`))
    *
-   * @method faker.finance.currencyCode
+   * @example
+   * faker.finance.currencyCode() // 'USD'
    */
   currencyCode(): string {
     return this.faker.random.objectElement(
@@ -160,9 +183,10 @@ export class Finance {
   }
 
   /**
-   * currencyName
+   * Returns a random currency name.
    *
-   * @method faker.finance.currencyName
+   * @example
+   * faker.finance.currencyName() // 'US Dollar'
    */
   currencyName(): string {
     return this.faker.random.objectElement(
@@ -172,9 +196,10 @@ export class Finance {
   }
 
   /**
-   * currencySymbol
+   * Returns a random currency symbol.
    *
-   * @method faker.finance.currencySymbol
+   * @example
+   * faker.finance.currencySymbol() // '$'
    */
   currencySymbol(): string {
     let symbol: string;
@@ -187,9 +212,10 @@ export class Finance {
   }
 
   /**
-   * bitcoinAddress
+   * Generates a random bitcoin address.
    *
-   * @method  faker.finance.bitcoinAddress
+   * @example
+   * faker.finance.bitcoinAddress() // '3ySdvCkTLVy7gKD4j6JfSaf5d'
    */
   bitcoinAddress(): string {
     const addressLength = this.faker.datatype.number({ min: 25, max: 34 });
@@ -205,9 +231,10 @@ export class Finance {
   }
 
   /**
-   * litecoinAddress
+   * Generates a random litecoin address.
    *
-   * @method faker.finance.litecoinAddress
+   * @example
+   * faker.finance.litecoinAddress() // 'MoQaSTGWBRXkWfyxKbNKuPrAWGELzcW'
    */
   litecoinAddress(): string {
     const addressLength = this.faker.datatype.number({ min: 26, max: 33 });
@@ -223,10 +250,14 @@ export class Finance {
   }
 
   /**
-   * Credit card number
+   * Generates a random credit card number.
+   *
+   * @param provider The (lowercase) name of the provider or the format used to generate one.
    *
-   * @method faker.finance.creditCardNumber
-   * @param provider scheme
+   * @example
+   * faker.finance.creditCardNumber() // '4427163488668'
+   * faker.finance.creditCardNumber('Visa') // '4882664999003'
+   * faker.finance.creditCardNumber('63[7-9]#-####-####-###L') // '6375-3265-4676-6644'
    */
   creditCardNumber(provider = ''): string {
     let format: string;
@@ -262,9 +293,10 @@ export class Finance {
   }
 
   /**
-   * Credit card CVV
+   * Generates a random credit card CVV.
    *
-   * @method faker.finance.creditCardCVV
+   * @example
+   * faker.finance.creditCardCVV() // '506'
    */
   creditCardCVV(): string {
     let cvv = '';
@@ -275,9 +307,10 @@ export class Finance {
   }
 
   /**
-   * ethereumAddress
+   * Generates a random ethereum Address.
    *
-   * @method faker.finance.ethereumAddress
+   * @example
+   * faker.finance.ethereumAddress() // '0xf03dfeecbafc5147241cc4c4ca20b3c9dfd04c4a'
    */
   ethereumAddress(): string {
     const address = this.faker.datatype.hexaDecimal(40).toLowerCase();
@@ -285,13 +318,16 @@ export class Finance {
   }
 
   /**
-   * iban
+   * Generates a random iban.
    *
-   * @param formatted Return a formatted version of the generated IBAN.
+   * @param formatted Return a formatted version of the generated IBAN. Defaults to `false`.
    * @param countryCode The country code from which you want to generate an IBAN, if none is provided a random country will be used.
    * @throws Will throw an error if the passed country code is not supported.
    *
-   * @method faker.finance.iban
+   * @example
+   * faker.finance.iban() // 'TR736918640040966092800056'
+   * faker.finance.iban(true) // 'FR20 8008 2330 8984 74S3 Z620 224'
+   * faker.finance.iban(true, 'DE') // 'DE84 1022 7075 0900 1170 01'
    */
   iban(formatted: boolean = false, countryCode?: string): string {
     let ibanFormat: {
@@ -357,9 +393,10 @@ export class Finance {
   }
 
   /**
-   * bic
+   * Generates a random bic.
    *
-   * @method faker.finance.bic
+   * @example
+   * faker.finance.bic() // 'WYAUPGX1432'
    */
   bic(): string {
     const vowels = ['A', 'E', 'I', 'O', 'U'];
@@ -381,9 +418,11 @@ export class Finance {
   }
 
   /**
-   * description
+   * Generates a random transaction description.
    *
-   * @method faker.finance.transactionDescription
+   * @example
+   * faker.finance.transactionDescription()
+   * // 'invoice transaction at Kilback - Durgan using card ending with ***(...4316) for UAH 783.82 in account ***16168663'
    */
   transactionDescription(): string {
     const transaction = this.Helpers.createTransaction();