chore: add JSDoc comments to address.ts (#230)

Co-authored-by: ST-DDT <[email protected]>

1 files changed, 143 insertions, 84 deletions

diff --git a/src/address.ts b/src/address.ts
index 66cd0ca2..7dde0bca 100644
--- a/src/address.ts
+++ b/src/address.ts
@@ -4,6 +4,9 @@ import type { Helpers } from './helpers';
 
 let f: Fake['fake'];
 
+/**
+ * Module to generate addresses and locations.
+ */
 export class Address {
   readonly Helpers: Helpers;
 
@@ -18,34 +21,21 @@ export class Address {
       }
       this[name] = this[name].bind(this);
     }
-
-    // TODO @Shinigami92 2022-01-13: Need better strategy
-    // @ts-expect-error
-    this.direction.schema = {
-      description:
-        'Generates a direction. Use optional useAbbr bool to return abbreviation',
-      sampleResults: ['Northwest', 'South', 'SW', 'E'],
-    };
-    // @ts-expect-error
-    this.cardinalDirection.schema = {
-      description:
-        'Generates a cardinal direction. Use optional useAbbr boolean to return abbreviation',
-      sampleResults: ['North', 'South', 'E', 'W'],
-    };
-    // @ts-expect-error
-    this.ordinalDirection.schema = {
-      description:
-        'Generates an ordinal direction. Use optional useAbbr boolean to return abbreviation',
-      sampleResults: ['Northwest', 'Southeast', 'SW', 'NE'],
-    };
   }
 
   /**
-   * Generates random zipcode from format. If format is not specified, the
+   * Generates random zipcode from specified format. If format is not specified, the
    * locale's zip format is used.
    *
-   * @method faker.address.zipCode
-   * @param format
+   * @param format The optional format used to generate the the zip code.
+   * By default, a random format is used from the locale zip formats.
+   *
+   * @example
+   * faker.address.zipCode() // '17839'
+   * faker.address.zipCode('####') // '6925'
+   *
+   * @see
+   * faker.helpers.replaceSymbols()
    */
   zipCode(format?: string): string {
     // if zip format is not specified, use the zip format defined for the locale
@@ -67,33 +57,41 @@ export class Address {
    * have a postcode_by_state definition, a random zip code is generated according
    * to the locale's zip format.
    *
-   * @method faker.address.zipCodeByState
-   * @param state
+   * @param state The abbreviation of the state to generate the zip code for.
+   *
+   * @example
+   * fakerUS.address.zipCodeByState("AK") // '99595'
+   * fakerUS.address.zipCodeByState("??") // '47683-9880'
    */
   zipCodeByState(state: string): string | number {
     const zipRange = this.faker.definitions.address.postcode_by_state[state];
     if (zipRange) {
+      // TODO ST-DDT 2022-02-10: Fix types
       return this.faker.datatype.number(zipRange);
     }
     return this.faker.address.zipCode();
   }
 
   /**
-   * Generates a random localized city name. The format string can contain any
-   * method provided by faker wrapped in `{{}}`, e.g. `{{name.firstName}}` in
+   * Generates a random localized city name.
+   *
+   * @param format The format to use. Can be either the index of the format to use or
+   * any method provided by faker wrapped in `{{}}`, e.g. `{{name.firstName}}` in
    * order to build the city name.
    *
    * If no format string is provided one of the following is randomly used:
    *
-   * * `{{address.cityPrefix}} {{name.firstName}}{{address.citySuffix}}`
-   * * `{{address.cityPrefix}} {{name.firstName}}`
-   * * `{{name.firstName}}{{address.citySuffix}}`
-   * * `{{name.lastName}}{{address.citySuffix}}`
-   * * `{{address.cityName}}` when city name is available
+   * - `{{address.cityPrefix}} {{name.firstName}}{{address.citySuffix}}`
+   * - `{{address.cityPrefix}} {{name.firstName}}`
+   * - `{{name.firstName}}{{address.citySuffix}}`
+   * - `{{name.lastName}}{{address.citySuffix}}`
+   * - `{{address.cityName}}` when city name is available
    *
-   * @method faker.address.city
-   * @param format
+   * @example
+   * faker.address.city() // 'Gleasonbury'
+   * faker.address.city(2) // 'Jadenshire'
    */
+  // TODO ST-DDT 2022-02-10: The string parameter doesn't work as expected.
   city(format?: string | number): string {
     const formats = [
       '{{address.cityPrefix}} {{name.firstName}}{{address.citySuffix}}',
@@ -114,9 +112,10 @@ export class Address {
   }
 
   /**
-   * Return a random localized city prefix
+   * Returns a random localized city prefix.
    *
-   * @method faker.address.cityPrefix
+   * @example
+   * faker.address.cityPrefix() // 'East'
    */
   cityPrefix(): string {
     return this.faker.random.arrayElement(
@@ -125,9 +124,10 @@ export class Address {
   }
 
   /**
-   * Return a random localized city suffix
+   * Returns a random localized city suffix.
    *
-   * @method faker.address.citySuffix
+   * @example
+   * faker.address.citySuffix() // 'mouth'
    */
   citySuffix(): string {
     return this.faker.random.arrayElement(
@@ -136,9 +136,10 @@ export class Address {
   }
 
   /**
-   * Returns a random city name
+   * Returns a random localized city name.
    *
-   * @method faker.address.cityName
+   * @example
+   * faker.address.cityName() // 'San Rafael'
    */
   cityName(): string {
     return this.faker.random.arrayElement(
@@ -147,9 +148,10 @@ export class Address {
   }
 
   /**
-   * Returns a random localized street name
+   * Generates a random localized street name.
    *
-   * @method faker.address.streetName
+   * @example
+   * faker.address.streetName() // 'Kulas Roads'
    */
   streetName(): string {
     let result: string;
@@ -174,10 +176,15 @@ export class Address {
   //
 
   /**
-   * Returns a random localized street address
+   * Generates a random localized street address.
    *
-   * @method faker.address.streetAddress
-   * @param useFullAddress
+   * @param useFullAddress When true this will generate a full address.
+   * Otherwise it will just generate a street address.
+   *
+   * @example
+   * faker.address.streetName() // '0917 O'Conner Estates'
+   * faker.address.streetAddress(true) // '3393 Ronny Way Apt. 742'
+   * faker.address.streetAddress(false) // '34830 Erdman Hollow'
    */
   streetAddress(useFullAddress: boolean = false): string {
     let address = '';
@@ -207,9 +214,10 @@ export class Address {
   }
 
   /**
-   * streetSuffix
+   * Returns a random localized street suffix.
    *
-   * @method faker.address.streetSuffix
+   * @example
+   * faker.address.streetSuffix() // 'Streets'
    */
   streetSuffix(): string {
     return this.faker.random.arrayElement(
@@ -218,9 +226,10 @@ export class Address {
   }
 
   /**
-   * streetPrefix
+   * Returns a random localized street prefix.
    *
-   * @method faker.address.streetPrefix
+   * @example
+   * fakerGH.address.streetPrefix() // 'Boame'
    */
   streetPrefix(): string {
     return this.faker.random.arrayElement(
@@ -229,9 +238,10 @@ export class Address {
   }
 
   /**
-   * secondaryAddress
+   * Generates a random localized secondary address.
    *
-   * @method faker.address.secondaryAddress
+   * @example
+   * faker.address.secondaryAddress() // 'Apt. 861'
    */
   secondaryAddress(): string {
     return this.Helpers.replaceSymbolWithNumber(
@@ -241,9 +251,10 @@ export class Address {
   }
 
   /**
-   * county
+   * Returns a random localized county.
    *
-   * @method faker.address.county
+   * @example
+   * faker.address.county() // 'Cambridgeshire'
    */
   county(): string {
     return this.faker.random.arrayElement(
@@ -252,9 +263,10 @@ export class Address {
   }
 
   /**
-   * country
+   * Returns a random country name.
    *
-   * @method faker.address.country
+   * @example
+   * faker.address.country() // 'Greece'
    */
   country(): string {
     return this.faker.random.arrayElement(
@@ -263,11 +275,18 @@ export class Address {
   }
 
   /**
-   * countryCode
+   * Returns a random country code.
+   *
+   * @param alphaCode The code to return. Can be either `'alpha-2'` (2 letter code)
+   * or `'alpha-3'` (three letter code). Defaults to `'alpha-2'`.
    *
-   * @method faker.address.countryCode
-   * @param alphaCode default alpha-2
+   * @example
+   * faker.address.countryCode() // 'SJ'
+   * faker.address.countryCode('alpha-2') // 'GA'
+   * faker.address.countryCode('alpha-3') // 'TJK'
+   * faker.address.countryCode('unsupported') // 'DJ'
    */
+  // TODO ST-DDT 2022-02-10: Limit the parameter to the two values.
   countryCode(alphaCode: string = 'alpha-2'): string {
     if (alphaCode === 'alpha-2') {
       return this.faker.random.arrayElement(
@@ -287,10 +306,12 @@ export class Address {
   }
 
   /**
-   * state
+   * Returns a random localized state from this country.
    *
-   * @method faker.address.state
-   * @param useAbbr
+   * @param useAbbr This parameter does nothing.
+   *
+   * @example
+   * faker.address.state() // 'Georgia'
    */
   // TODO @Shinigami92 2022-01-13: useAbbr not in use
   state(useAbbr?: boolean): string {
@@ -298,9 +319,10 @@ export class Address {
   }
 
   /**
-   * stateAbbr
+   * Returns a random localized state's abbreviated name from this country.
    *
-   * @method faker.address.stateAbbr
+   * @example
+   * faker.address.stateAbbr() // 'ND'
    */
   stateAbbr(): string {
     return this.faker.random.arrayElement(
@@ -309,12 +331,15 @@ export class Address {
   }
 
   /**
-   * latitude
+   * Generates a random latitude.
+   *
+   * @param max The upper bound for the latitude to generate. Defaults to `90`.
+   * @param min The lower bound for the latitude to generate. Defaults to `-90`.
+   * @param precision The number of decimal points of precision for the latitude. Defaults to `4`.
    *
-   * @method faker.address.latitude
-   * @param max default is 90
-   * @param min default is -90
-   * @param precision default is 4
+   * @example
+   * faker.address.latitude() // '-30.9501'
+   * faker.address.latitude(10, -10, 5) // '2.68452'
    */
   latitude(max: number = 90, min: number = -90, precision: number = 4): string {
     return this.faker.datatype
@@ -327,12 +352,15 @@ export class Address {
   }
 
   /**
-   * longitude
+   * Generates a random longitude.
    *
-   * @method faker.address.longitude
-   * @param max default is 180
-   * @param min default is -180
-   * @param precision default is 4
+   * @param max The upper bound for the longitude to generate. Defaults to `180`.
+   * @param min The lower bound for the longitude to generate. Defaults to `-180`.
+   * @param precision The number of decimal points of precision for the longitude. Defaults to `4`.
+   *
+   * @example
+   * faker.address.longitude() // '-154.0226'
+   * faker.address.longitude(10, -10, 5) // '-4.03620'
    */
   longitude(
     max: number = 180,
@@ -349,10 +377,15 @@ export class Address {
   }
 
   /**
-   *  direction
+   * Returns a random direction (cardinal and ordinal; northwest, east, etc).
+   *
+   * @param useAbbr If true this will return abbreviated directions (NW, E, etc).
+   * Otherwise this will return the long name. Defaults to `false`.
    *
-   * @method faker.address.direction
-   * @param useAbbr return direction abbreviation. defaults to false
+   * @example
+   * faker.address.direction() // 'Northeast'
+   * faker.address.direction(false) // 'South'
+   * faker.address.direction(true) // 'NE'
    */
   direction(useAbbr: boolean = false): string {
     if (!useAbbr) {
@@ -366,10 +399,15 @@ export class Address {
   }
 
   /**
-   * cardinal direction
+   * Returns a random cardinal direction (north, east, south, west).
    *
-   * @method faker.address.cardinalDirection
-   * @param useAbbr return direction abbreviation. defaults to false
+   * @param useAbbr If true this will return abbreviated directions (N, E, etc).
+   * Otherwise this will return the long name. Defaults to `false`.
+   *
+   * @example
+   * faker.address.cardinalDirection() // 'North'
+   * faker.address.cardinalDirection(false) // 'South'
+   * faker.address.cardinalDirection(true) // 'N'
    */
   cardinalDirection(useAbbr: boolean = false): string {
     if (!useAbbr) {
@@ -383,10 +421,15 @@ export class Address {
   }
 
   /**
-   * ordinal direction
+   * Returns a random ordinal direction (northwest, southeast, etc).
+   *
+   * @param useAbbr If true this will return abbreviated directions (NW, SE, etc).
+   * Otherwise this will return the long name. Defaults to `false`.
    *
-   * @method faker.address.ordinalDirection
-   * @param useAbbr return direction abbreviation. defaults to false
+   * @example
+   * faker.address.ordinalDirection() // 'Northeast'
+   * faker.address.ordinalDirection(false) // 'Northwest'
+   * faker.address.ordinalDirection(true) // 'NE'
    */
   ordinalDirection(useAbbr: boolean = false): string {
     if (!useAbbr) {
@@ -399,11 +442,26 @@ export class Address {
     );
   }
 
+  /**
+   * Generates a random GPS coordinate within the specified radius from the given coordinate.
+   *
+   * @param coordinate The original coordinate to get a new coordinate close to.
+   * If no coordinate is given, a random one will be chosen.
+   * @param radius The maximum distance from the given coordinate to the new coordinate. Defaults to `10`.
+   * @param isMetric If `true` assume the radius to be in kilometers. If `false` for miles. Defaults to `false`.
+   *
+   * @example
+   * faker.address.nearbyGPSCoordinate() // [ '33.8475', '-170.5953' ]
+   * faker.address.nearbyGPSCoordinate([33, -170]) // [ '33.0165', '-170.0636' ]
+   * faker.address.nearbyGPSCoordinate([33, -170], 1000, true) // [ '37.9163', '-179.2408' ]
+   */
+  // TODO ST-DDT 2022-02-10: This should use either string or number coords.
   nearbyGPSCoordinate(
     coordinate?: number[],
     radius?: number,
     isMetric?: boolean
   ): string[] {
+    // TODO ST-DDT 2022-02-10: Remove unused code.
     function randomFloat(min: number, max: number): number {
       return Math.random() * (max - min) + min;
     }
@@ -471,9 +529,10 @@ export class Address {
   }
 
   /**
-   * Return a random time zone
+   * Returns a random time zone.
    *
-   * @method faker.address.timeZone
+   * @example
+   * faker.address.timeZone() // 'Pacific/Guam'
    */
   timeZone(): string {
     return this.faker.random.arrayElement(