docs: update src files

Author: dmihaylo

src/cldr.d.ts

@@ -3,17 +3,17 @@
  */
 export interface DateFormatNameOptions {
     /**
-     * Specifies the type of names.
+     * Specifies the type of the names.
      */
     type: 'dayPeriods' | 'days' | 'months' | 'quarters' | 'eras';
 
     /**
-     * Specifies the names form.
+     * Specifies the form of the names.
      */
     nameType: 'abbreviated' | 'narrow' | 'short' | 'wide';
 
     /**
-     * Specifies if the returned names should be converted to lower case.
+     * Specifies whether the returned names should be converted to lower case.
      */
     lower?: boolean;
 
@@ -26,14 +26,14 @@ export interface DateFormatNameOptions {
 /**
  * Returns the names from the specified locale based on the options.
  *
- * @param locale The locale id which defines the locale from which the names should be retrieved.
- * @param options The options that determine the returned names.
- * @returns The date format names.
+ * @param locale - The locale `id` which defines the locale from which the names should be retrieved.
+ * @param options - The options that determine the returned names.
+ * @returns - The date format names.
  */
 export function dateFormatNames(locale: string, options: DateFormatNameOptions): any;
 
 /**
- * Settings for the dateFieldName function.
+ * Settings for the `dateFieldName` function.
  */
 export interface DateFieldNameOptions {
     /**
@@ -60,7 +60,7 @@ export interface DateFieldNameOptions {
 }
 
 /**
- * Returns a localized date field name based on a specific format specifier.
+ * Returns a localized date-field name based on a specific format specifier.
  *
  * The available `type` values are:
  * - `era`
@@ -80,9 +80,9 @@ export interface DateFieldNameOptions {
  * - `narrow`
  * - `short`
  *
- * @param options Detailed configuration for the desired date field name.
- * @param locale The optional locale id. If not specified, the `"en"` locale id is used.
- * @returns The localized date field name from the current locale based on the option.
+ * @param options - Detailed configuration for the desired date-field name.
+ * @param locale - The optional locale `id`. If not specified, the `id` of the `"en"` locale is used.
+ * @returns - The localized date-field name from the current locale based on the option.
  *
  *
  * @example
@@ -96,25 +96,25 @@ export interface DateFieldNameOptions {
 export function dateFieldName(options: DateFieldNameOptions, locale?: string): string;
 
 /**
- * Returns the first day index starting from Sunday based on the specified locale.
+ * Returns the first-day index starting from Sunday and based on the specified locale.
  *
- * @param locale The locale id.
- * @returns The first day index.
+ * @param locale - The locale `id`.
+ * @returns - The first-day index.
  */
 export function firstDay(locale: string): number;
 
 /**
  * Loads CLDR data.
  *
- * @param data The CLDR data to be loaded. Accepts multiple parameters.
+ * @param data - The CLDR data to be loaded. Accepts multiple parameters.
  */
 export function load(...data: any[]): void;
 
 /**
  * Returns the number symbols from the specified locale.
  *
- * @param locale The locale id which defines the locale for which the number symbols should be returned.
- * @returns The number symbols.
+ * @param locale - The locale `id` that defines the locale for which the number symbols should be returned.
+ * @returns - The number symbols.
  */
 export function numberSymbols(locale: string): any;
 

src/dates.d.ts

@@ -1,16 +1,17 @@
 import { DateFormatNameOptions } from './cldr';
 
 /**
- * Settings for the formatDate and parseDate functions.
+ * Settings for the `formatDate` and `parseDate` functions.
  */
 export interface DateFormatOptions {
     /**
-     * Defines the skeleton format used to get the pattern from the locale calendar [`availableFormats`](http://www.unicode.org/reports/tr35/tr35-dates.html#availableFormats_appendItems).
+     * Defines the skeleton format that is used to get the pattern from the
+     * [`availableFormats`](http://www.unicode.org/reports/tr35/tr35-dates.html#availableFormats_appendItems) of the locale calendar.
      */
     skeleton?: string;
 
     /**
-     * Defines the exact pattern to be used to format the date.
+     * Defines the exact pattern that will be used to format the date.
      */
     pattern?: string;
 
@@ -30,7 +31,7 @@ export interface DateFormatOptions {
     datetime?: 'short' | 'medium' | 'long' | 'full';
 
     /**
-     * Specifies how should the date era be formatted.
+     * Specifies how the date era should be formatted.
      */
     era?: 'narrow' | 'short' | 'long';
 
@@ -60,7 +61,7 @@ export interface DateFormatOptions {
     hour?: 'numeric' | '2-digit';
 
     /**
-     * Specifies if a 12-hour time set should be used for the formatting.
+     * Specifies whether a 12-hour time-set should be used for the formatting.
      */
     hour12?: boolean;
 
@@ -75,28 +76,28 @@ export interface DateFormatOptions {
     second?: 'numeric' | '2-digit';
 
     /**
-     * Specifies how the timezone should be formatted.
+     * Specifies how the time-zone should be formatted.
      */
     timeZoneName?: 'short' | 'long';
 }
 
 /**
  * Converts a `Date` object to a string based on the specified format and locale.
  *
- * @param value Defines the date to be formatted.
- * @param format Defines a string representing a predefined or custom date format, or a configuration object.
- * @param locale The optional locale id. If not specified, the `"en"` locale id is used.
- * @returns The formatted date.
+ * @param value - Defines the date that will be formatted.
+ * @param format - Defines a string that represents a predefined or custom date format, or a configuration object.
+ * @param locale - The optional locale `id`. If not specified, the `id` of the `"en"` locale is used.
+ * @returns - The formatted date.
  */
 export function formatDate(value: Date, format: string|DateFormatOptions, locale?: string): string;
 
 /**
  * Converts a string to a `Date` object based on the specified format and locale.
  *
- * @param value Defines the string to be parsed.
- * @param format Defines a string representing a predefined or custom date format, a configuration object, or an array of formats that should be used to parse the value.
- * @param locale The optional locale id. If not specified, the `"en"` locale id is used.
- * @returns The parsed date.
+ * @param value - Defines the string that will be parsed.
+ * @param format - Defines a string that represents a predefined or custom date format, a configuration object, or an array of formats that should be used to parse the value.
+ * @param locale - The optional locale `id`. If not specified, the `id` of the `"en"` locale is used.
+ * @returns - The parsed date.
  */
 export function parseDate(value: string, format?: string | DateFormatOptions | string[] | DateFormatOptions[], locale?: string): Date;
 
@@ -121,10 +122,10 @@ export interface DateFormatPart {
 }
 
 /**
- * Splits the date format into objects containing information about each part of the pattern.
+ * Splits the date format into objects that contain information about each part of the pattern.
  *
- * @param format The format string or options.
- * @param locale The optional locale id. If not specified, the `"en"` locale id is used.
- * @returns The date format parts.
+ * @param format - The format string or options.
+ * @param locale - The optional locale `id`. If not specified, the `id` of the `"en"` locale is used.
+ * @returns - The date format parts.
  */
 export function splitDateFormat(format: string|DateFormatOptions, locale?: string): DateFormatPart[];

src/format.d.ts

@@ -1,19 +1,19 @@
 /**
  * Formats dates and numbers based on the specified format and locale.
  *
- * @param value The value to be formatted.
- * @param format A string representing a predefined or custom date or number format, or a configuration object.
- * @param locale The optional locale id. If not specified, the `"en"` locale id is used.
- * @returns The formatted value.
+ * @param value - The value that will be formatted.
+ * @param format - A string that represents a predefined or custom date or number format, or a configuration object.
+ * @param locale - The optional locale `id`. If not specified, the `id` of the `"en"` locale is used.
+ * @returns - The formatted value.
  */
 export function toString(value: string | Date | number, format: string | any, locale?: string): string;
 
 /**
  * Replaces the format string placeholders with the provided values based on the index.
  *
- * @param format The format string.
- * @param values The values that should be replaced in the format string.
- * @param locale The optional locale id. If not specified, the `"en"` locale id is used.
- * @returns The format string with replaced formatted values.
+ * @param format - The format string.
+ * @param values - The values that should be replaced in the format string.
+ * @param locale - The optional locale `id`. If not specified, the `id` of the `"en"` locale is used.
+ * @returns - The format string with replaced formatted values.
  */
 export function format(format: string, values: any[], locale?: string): string;

src/numbers.d.ts

@@ -1,5 +1,5 @@
 /**
- * Settings for the formatNumber and parseNumber functions.
+ * Settings for the `formatNumber` and `parseNumber` functions.
  */
 export interface NumberFormatOptions {
 
@@ -9,7 +9,8 @@ export interface NumberFormatOptions {
     style?: 'decimal' | 'currency' | 'percent' | 'scientific';
 
     /**
-     * Defines the currency code of the currency used in the formatting. If not specified, the default currency for the locale is used.
+     * Defines the currency code of the currency that is used in the formatting.
+     * If not specified, the default currency for the locale is used.
      */
     currency?: string;
 
@@ -24,42 +25,44 @@ export interface NumberFormatOptions {
     useGrouping?: boolean;
 
     /**
-     * Defines the minimum number of integer digits to be used in the formatting.
+     * Defines the minimum number of integer digits that will be used in the formatting.
      */
     minimumIntegerDigits?: number;
 
     /**
-     * Defines the minimum number of fraction digits to use.
-     * The default value for the decimal and percent formatting is 0 (zero).
-     * The default value of the currency formatting is the number of digits for the currency from the supplemental `currencyData` or 2 if no info is provided for the currency.
+     * Defines the minimum number of fraction digits that will be used.
+     * The default value of the decimal and percent formatting is `0` (zero).
+     * The default value of the currency formatting is the number of digits for the currency from the supplemental `currencyData`.
+     * If no information about the currency is provided, the default value of the currency formatting is `2`.
      */
     minimumFractionDigits?: number;
 
     /**
-     * Defines the maximum number of fraction digits to be used.
-     * The default value of the decimal formatting is the greater one between `minimumFractionDigits` and 3.
-     * The default value of the currency formatting is the greater one between `minimumFractionDigits` and the number of digits for the currency from the supplemental  `currencyData` or 2 if no info is provided for the currency.
-     * The default value of the percent formatting is the greater one between `minimumFractionDigits` and 0 (zero).
+     * Defines the maximum number of fraction digits that will be used.
+     * The default value of the decimal formatting is the greater one between `minimumFractionDigits` and `3`.
+     * The default value of the currency formatting is the greater one between `minimumFractionDigits` and the number of digits for the currency from the supplemental `currencyData`.
+     * If no information about the currency is provided, the default value of the currency formatting is the greater one between `minimumFractionDigits` and `2`.
+     * The default value of the percent formatting is the greater one between `minimumFractionDigits` and `0` (zero).
      */
     maximumFractionDigits?: number;
 }
 
 /**
  * Converts a string to a `Number` based on the specified locale.
  *
- * @param value The string to be parsed.
- * @param locale The locale id defining the locale which information should be used to parse the string.
- * @param format The format used to parse the string. Usefull if parsing non-default currencies.
- * @returns The parsed number.
+ * @param value - The string that will be parsed.
+ * @param locale - The locale `id` that defines the locale whose information should be used to parse the string.
+ * @param format - The format that is used to parse the string. Useful when non-default currencies are parsed.
+ * @returns - The parsed number.
  */
 export function parseNumber(value: string, locale?: string, format?: string|NumberFormatOptions): number;
 
 /**
  * Converts a `Number` to a string based on the specified format and locale.
  *
- * @param value The number to be formatted.
- * @param format The format to be applied.
- * @param locale The locale id defining the locale which information should be used for the formatting.
- * @returns The formatted number.
+ * @param value - The number that will be formatted.
+ * @param format - The format that will be applied.
+ * @param locale - The locale `id` that defines the locale whose information should be used for the formatting.
+ * @returns - The formatted number.
  */
-export function formatNumber(value: number, format: string|NumberFormatOptions, locale?: string): string;
+export function formatNumber(value: number, format: string|NumberFormatOptions, locale?: string): string;