From 333bfa0ffb189cfd4eb45695a960f6a8672dc880 Mon Sep 17 00:00:00 2001 From: Judy Bogart Date: Wed, 27 Feb 2019 12:40:52 -0800 Subject: [PATCH] docs: api doc for i18n (#29289) PR Close #29289 --- packages/common/src/i18n/format_date.ts | 21 +- packages/common/src/i18n/format_number.ts | 53 ++- packages/common/src/i18n/locale_data_api.ts | 442 +++++++++++------- .../core/src/di/injector_compatibility.ts | 20 +- 4 files changed, 339 insertions(+), 197 deletions(-) diff --git a/packages/common/src/i18n/format_date.ts b/packages/common/src/i18n/format_date.ts index 92eb14572a..b25921e5dd 100644 --- a/packages/common/src/i18n/format_date.ts +++ b/packages/common/src/i18n/format_date.ts @@ -46,17 +46,18 @@ enum TranslationType { * * Formats a date according to locale rules. * - * Where: - * - `value` is a Date, a number (milliseconds since UTC epoch) or an ISO string - * (https://www.w3.org/TR/NOTE-datetime). - * - `format` indicates which date/time components to include. See {@link DatePipe} for more - * details. - * - `locale` is a `string` defining the locale to use. - * - `timezone` to be used for formatting. It understands UTC/GMT and the continental US time zone - * abbreviations, but for general use, use a time zone offset (e.g. `'+0430'`). - * If not specified, host system settings are used. + * @param value The date to format, as a number (milliseconds since UTC epoch) + * or an [ISO date-time string](https://www.w3.org/TR/NOTE-datetime). + * @param format The date-time components to include. See `DatePipe` for details. + * @param locale A locale code for the locale format rules to use. + * @param timezone The time zone. A time zone offset from GMT (such as `'+0430'`), + * or a standard UTC/GMT or continental US time zone abbreviation. + * If not specified, uses host system settings. * - * See {@link DatePipe} for more details. + * @returns The formatted date string. + * + * @see `DatePipe` + * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n) * * @publicApi */ diff --git a/packages/common/src/i18n/format_number.ts b/packages/common/src/i18n/format_number.ts index 9f66142c20..0c17710273 100644 --- a/packages/common/src/i18n/format_number.ts +++ b/packages/common/src/i18n/format_number.ts @@ -19,7 +19,7 @@ const CURRENCY_CHAR = '¤'; const PERCENT_CHAR = '%'; /** - * Transforms a number to a locale string based on a style and a format + * Transforms a number to a locale string based on a style and a format. */ function formatNumberToLocaleString( value: number, pattern: ParsedNumberFormat, locale: string, groupSymbol: NumberSymbol, @@ -128,15 +128,21 @@ function formatNumberToLocaleString( * * Formats a number as currency using locale rules. * - * Use `currency` to format a number as currency. + * @param value The number to format. + * @param locale A locale code for the locale format rules to use. + * @param currency A string containing the currency symbol or its name, + * such as "$" or "Canadian Dollar". Used in output string, but does not affect the operation + * of the function. + * @param currencyCode The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) + * currency code to use in the result string, such as `USD` for the US dollar and `EUR` for the euro. + * @param digitInfo Decimal representation options, specified by a string in the following format: + * `{minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}`. See `DecimalPipe` for more details. * - * Where: - * - `value` is a number. - * - `locale` is a `string` defining the locale to use. - * - `currency` is the string that represents the currency, it can be its symbol or its name. - * - `currencyCode` is the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code, such - * as `USD` for the US dollar and `EUR` for the euro. - * - `digitInfo` See {@link DecimalPipe} for more details. + * @returns The formatted currency value. + * + * @see `formatNumber()` + * @see `DecimalPipe` + * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n) * * @publicApi */ @@ -163,12 +169,18 @@ export function formatCurrency( * * Formats a number as a percentage according to locale rules. * - * Where: - * - `value` is a number. - * - `locale` is a `string` defining the locale to use. - * - `digitInfo` See {@link DecimalPipe} for more details. + * @param value The number to format. + * @param locale A locale code for the locale format rules to use. + * @param digitInfo Decimal representation options, specified by a string in the following format: + * `{minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}`. See `DecimalPipe` for more details. * + * @returns The formatted percentage value. + * + * @see `formatNumber()` + * @see `DecimalPipe` + * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n) * @publicApi + * */ export function formatPercent(value: number, locale: string, digitsInfo?: string): string { const format = getLocaleNumberFormat(locale, NumberFormatStyle.Percent); @@ -183,13 +195,16 @@ export function formatPercent(value: number, locale: string, digitsInfo?: string * @ngModule CommonModule * @description * - * Formats a number as text. Group sizing and separator and other locale-specific - * configurations are based on the locale. + * Formats a number as text, with group sizing, separator, and other + * parameters based on the locale. * - * Where: - * - `value` is a number. - * - `locale` is a `string` defining the locale to use. - * - `digitInfo` See {@link DecimalPipe} for more details. + * @param value The number to format. + * @param locale A locale code for the locale format rules to use. + * @param digitInfo Decimal representation options, specified by a string in the following format: + * `{minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}`. See `DecimalPipe` for more details. + * + * @returns The formatted text string. + * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n) * * @publicApi */ diff --git a/packages/common/src/i18n/locale_data_api.ts b/packages/common/src/i18n/locale_data_api.ts index 1791387b82..46d02421cc 100644 --- a/packages/common/src/i18n/locale_data_api.ts +++ b/packages/common/src/i18n/locale_data_api.ts @@ -11,8 +11,9 @@ import {LOCALE_DATA, LocaleDataIndex, ExtraLocaleDataIndex, CurrencyIndex} from import {CURRENCIES_EN, CurrenciesSymbols} from './currencies'; /** - * The different format styles that can be used to represent numbers. - * Used by the function {@link getLocaleNumberFormat}. + * Format styles that can be used to represent numbers. + * @see `getLocaleNumberFormat()`. + * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n) * * @publicApi */ @@ -23,7 +24,14 @@ export enum NumberFormatStyle { Scientific } -/** @publicApi */ +/** + * Plurality cases used for translating plurals to different languages. + * + * @see `NgPlural` + * @see `NgPluralCase` + * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n) + * + * @publicApi */ export enum Plural { Zero = 0, One = 1, @@ -34,11 +42,11 @@ export enum Plural { } /** - * Some languages use two different forms of strings (standalone and format) depending on the - * context. - * Typically the standalone version is the nominative form of the word, and the format version is in - * the genitive. - * See [the CLDR website](http://cldr.unicode.org/translation/date-time) for more information. + * Context-dependant translation forms for strings. + * Typically the standalone version is for the nominative form of the word, + * and the format version is used for the genitive case. + * @see [CLDR website](http://cldr.unicode.org/translation/date-time#TOC-Stand-Alone-vs.-Format-Styles) + * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n) * * @publicApi */ @@ -48,85 +56,143 @@ export enum FormStyle { } /** - * Multiple widths are available for translations: narrow (1 character), abbreviated (3 characters), - * wide (full length), and short (2 characters, only for days). - * - * For example the day `Sunday` will be: - * - Narrow: `S` - * - Short: `Su` - * - Abbreviated: `Sun` - * - Wide: `Sunday` + * String widths available for translations. + * The specific character widths are locale-specific. + * Examples are given for the word "Sunday" in English. * * @publicApi */ export enum TranslationWidth { + /** 1 character for `en-US`. For example: 'S' */ Narrow, + /** 3 characters for `en-US`. For example: 'Sun' */ Abbreviated, + /** Full length for `en-US`. For example: "Sunday" */ Wide, + /** 2 characters for `en-US`, For example: "Su" */ Short } /** - * Multiple widths are available for formats: short (minimal amount of data), medium (small amount - * of data), long (complete amount of data), full (complete amount of data and extra information). - * - * For example the date-time formats for the english locale will be: - * - `'short'`: `'M/d/yy, h:mm a'` (e.g. `6/15/15, 9:03 AM`) - * - `'medium'`: `'MMM d, y, h:mm:ss a'` (e.g. `Jun 15, 2015, 9:03:01 AM`) - * - `'long'`: `'MMMM d, y, h:mm:ss a z'` (e.g. `June 15, 2015 at 9:03:01 AM GMT+1`) - * - `'full'`: `'EEEE, MMMM d, y, h:mm:ss a zzzz'` (e.g. `Monday, June 15, 2015 at - * 9:03:01 AM GMT+01:00`) + * String widths available for date-time formats. + * The specific character widths are locale-specific. + * Examples are given for `en-US`. * + * @see `getLocaleDateFormat()` + * @see `getLocaleTimeFormat()`` + * @see `getLocaleDateTimeFormat()` + * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n) * @publicApi */ export enum FormatWidth { + /** + * For `en-US`, 'M/d/yy, h:mm a'` + * (Example: `6/15/15, 9:03 AM`) + */ Short, + /** + * For `en-US`, `'MMM d, y, h:mm:ss a'` + * (Example: `Jun 15, 2015, 9:03:01 AM`) + */ Medium, + /** + * For `en-US`, `'MMMM d, y, h:mm:ss a z'` + * (Example: `June 15, 2015 at 9:03:01 AM GMT+1`) + */ Long, + /** + * For `en-US`, `'EEEE, MMMM d, y, h:mm:ss a zzzz'` + * (Example: `Monday, June 15, 2015 at 9:03:01 AM GMT+01:00`) + */ Full } /** - * Number symbol that can be used to replace placeholders in number patterns. - * The placeholders are based on english values: + * Symbols that can be used to replace placeholders in number patterns. + * Examples are based on `en-US` values. * - * | Name | Example for en-US | Meaning | - * |------------------------|-------------------|---------------------------------------------| - * | decimal | 2,345`.`67 | decimal separator | - * | group | 2`,`345.67 | grouping separator, typically for thousands | - * | plusSign | `+`23 | the plus sign used with numbers | - * | minusSign | `-`23 | the minus sign used with numbers | - * | percentSign | 23.4`%` | the percent sign (out of 100) | - * | perMille | 234`‰` | the permille sign (out of 1000) | - * | exponential | 1.2`E`3 | used in computers for 1.2×10³. | - * | superscriptingExponent | 1.2`×`103 | human-readable format of exponential | - * | infinity | `∞` | used in +∞ and -∞. | - * | nan | `NaN` | "not a number". | - * | timeSeparator | 10`:`52 | symbol used between time units | - * | currencyDecimal | $2,345`.`67 | decimal separator, fallback to "decimal" | - * | currencyGroup | $2`,`345.67 | grouping separator, fallback to "group" | + * @see `getLocaleNumberSymbol()` + * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n) * * @publicApi */ export enum NumberSymbol { + /** + * Decimal separator. + * For `en-US`, the dot character. + * Example : 2,345`.`67 + */ Decimal, + /** + * Grouping separator, typically for thousands. + * For `en-US`, the comma character. + * Example: 2`,`345.67 + */ Group, + /** + * List-item separator. + * Example: "one, two, and three" + */ List, + /** + * Sign for percentage (out of 100). + * Example: 23.4% + */ PercentSign, + /** + * Sign for positive numbers. + * Example: +23 + */ PlusSign, + /** + * Sign for negative numbers. + * Example: -23 + */ MinusSign, + /** + * Computer notation for exponential value (n times a power of 10). + * Example: 1.2E3 + */ Exponential, + /** + * Human-readable format of exponential. + * Example: 1.2x103 + */ SuperscriptingExponent, + /** + * Sign for permille (out of 1000). + * Example: 23.4‰ + */ PerMille, + /** + * Infinity, can be used with plus and minus. + * Example: ∞, +∞, -∞ + */ Infinity, + /** + * Not a number. + * Example: NaN + */ NaN, + /** + * Symbol used between time units. + * Example: 10:52 + */ TimeSeparator, + /** + * Decimal separator for currency values (fallback to `Decimal`). + * Example: $2,345.67 + */ CurrencyDecimal, + /** + * Group separator for currency values (fallback to `Group`). + * Example: $2,345.67 + */ CurrencyGroup } /** - * The value for each day of the week, based on the en-US locale + * The value for each day of the week, based on the `en-US` locale * * @publicApi */ @@ -141,7 +207,11 @@ export enum WeekDay { } /** - * The locale id for the chosen locale (e.g `en-GB`). + * Retrieves the locale ID from the currently loaded locale. + * The loaded locale could be, for example, a global one rather than a regional one. + * @param locale A locale code, such as `fr-FR`. + * @returns The locale code. For example, `fr`. + * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n) * * @publicApi */ @@ -150,7 +220,13 @@ export function getLocaleId(locale: string): string { } /** - * Periods of the day (e.g. `[AM, PM]` for en-US). + * Retrieves day period strings for the given locale. + * + * @param locale A locale code for the locale format rules to use. + * @param formStyle The required grammatical form. + * @param width The required character width. + * @returns An array of localized period strings. For example, `[AM, PM]` for `en-US`. + * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n) * * @publicApi */ @@ -165,7 +241,14 @@ export function getLocaleDayPeriods( } /** - * Days of the week for the Gregorian calendar (e.g. `[Sunday, Monday, ... Saturday]` for en-US). + * Retrieves days of the week for the given locale, using the Gregorian calendar. + * + * @param locale A locale code for the locale format rules to use. + * @param formStyle The required grammatical form. + * @param width The required character width. + * @returns An array of localized name strings. + * For example,`[Sunday, Monday, ... Saturday]` for `en-US`. + * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n) * * @publicApi */ @@ -179,7 +262,14 @@ export function getLocaleDayNames( } /** - * Months of the year for the Gregorian calendar (e.g. `[January, February, ...]` for en-US). + * Retrieves months of the year for the given locale, using the Gregorian calendar. + * + * @param locale A locale code for the locale format rules to use. + * @param formStyle The required grammatical form. + * @param width The required character width. + * @returns An array of localized name strings. + * For example, `[January, February, ...]` for `en-US`. + * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n) * * @publicApi */ @@ -193,7 +283,14 @@ export function getLocaleMonthNames( } /** - * Eras for the Gregorian calendar (e.g. AD/BC). + * Retrieves Gregorian-calendar eras for the given locale. + * @param locale A locale code for the locale format rules to use. + * @param formStyle The required grammatical form. + * @param width The required character width. + + * @returns An array of localized era strings. + * For example, `[AD, BC]` for `en-US`. + * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n) * * @publicApi */ @@ -204,8 +301,13 @@ export function getLocaleEraNames(locale: string, width: TranslationWidth): [str } /** - * First day of the week for this locale, based on english days (Sunday = 0, Monday = 1, ...). - * For example in french the value would be 1 because the first day of the week is Monday. + * Retrieves the first day of the week for the given locale. + * + * @param locale A locale code for the locale format rules to use. + * @returns A day index number, using the 0-based week-day index for `en-US` + * (Sunday = 0, Monday = 1, ...). + * For example, for `fr-FR`, returns 1 to indicate that the first day is Monday. + * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n) * * @publicApi */ @@ -215,9 +317,11 @@ export function getLocaleFirstDayOfWeek(locale: string): WeekDay { } /** - * Range of days in the week that represent the week-end for this locale, based on english days - * (Sunday = 0, Monday = 1, ...). - * For example in english the value would be [6,0] for Saturday to Sunday. + * Range of week days that are considered the week-end for the given locale. + * + * @param locale A locale code for the locale format rules to use. + * @returns The range of day values, `[startDay, endDay]`. + * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n) * * @publicApi */ @@ -227,27 +331,13 @@ export function getLocaleWeekEndRange(locale: string): [WeekDay, WeekDay] { } /** - * Date format that depends on the locale. + * Retrieves a localized date-value formating string. * - * There are four basic date formats: - * - `full` should contain long-weekday (EEEE), year (y), long-month (MMMM), day (d). - * - * For example, English uses `EEEE, MMMM d, y`, corresponding to a date like - * "Tuesday, September 14, 1999". - * - * - `long` should contain year, long-month, day. - * - * For example, `MMMM d, y`, corresponding to a date like "September 14, 1999". - * - * - `medium` should contain year, abbreviated-month (MMM), day. - * - * For example, `MMM d, y`, corresponding to a date like "Sep 14, 1999". - * For languages that do not use abbreviated months, use the numeric month (MM/M). For example, - * `y/MM/dd`, corresponding to a date like "1999/09/14". - * - * - `short` should contain year, numeric-month (MM/M), and day. - * - * For example, `M/d/yy`, corresponding to a date like "9/14/99". + * @param locale A locale code for the locale format rules to use. + * @param width The format type. + * @returns The localized formating string. + * @see `FormatWidth` + * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n) * * @publicApi */ @@ -257,23 +347,14 @@ export function getLocaleDateFormat(locale: string, width: FormatWidth): string } /** - * Time format that depends on the locale. - * - * The standard formats include four basic time formats: - * - `full` should contain hour (h/H), minute (mm), second (ss), and zone (zzzz). - * - `long` should contain hour, minute, second, and zone (z) - * - `medium` should contain hour, minute, second. - * - `short` should contain hour, minute. - * - * Note: The patterns depend on whether the main country using your language uses 12-hour time or - * not: - * - For 12-hour time, use a pattern like `hh:mm a` using h to mean a 12-hour clock cycle running - * 1 through 12 (midnight plus 1 minute is 12:01), or using K to mean a 12-hour clock cycle - * running 0 through 11 (midnight plus 1 minute is 0:01). - * - For 24-hour time, use a pattern like `HH:mm` using H to mean a 24-hour clock cycle running 0 - * through 23 (midnight plus 1 minute is 0:01), or using k to mean a 24-hour clock cycle running - * 1 through 24 (midnight plus 1 minute is 24:01). + * Retrieves a localized time-value formatting string. * + * @param locale A locale code for the locale format rules to use. + * @param width The format type. + * @returns The localized formatting string. + * @see `FormatWidth` + * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n) + * @publicApi */ export function getLocaleTimeFormat(locale: string, width: FormatWidth): string { @@ -282,27 +363,13 @@ export function getLocaleTimeFormat(locale: string, width: FormatWidth): string } /** - * Date-time format that depends on the locale. + * Retrieves a localized date-time formatting string. * - * The date-time pattern shows how to combine separate patterns for date (represented by {1}) - * and time (represented by {0}) into a single pattern. It usually doesn't need to be changed. - * What you want to pay attention to are: - * - possibly removing a space for languages that don't use it, such as many East Asian languages - * - possibly adding a comma, other punctuation, or a combining word - * - * For example: - * - English uses `{1} 'at' {0}` or `{1}, {0}` (depending on date style), while Japanese uses - * `{1}{0}`. - * - An English formatted date-time using the combining pattern `{1}, {0}` could be - * `Dec 10, 2010, 3:59:49 PM`. Notice the comma and space between the date portion and the time - * portion. - * - * There are four formats (`full`, `long`, `medium`, `short`); the determination of which to use - * is normally based on the date style. For example, if the date has a full month and weekday - * name, the full combining pattern will be used to combine that with a time. If the date has - * numeric month, the short version of the combining pattern will be used to combine that with a - * time. English uses `{1} 'at' {0}` for full and long styles, and `{1}, {0}` for medium and short - * styles. + * @param locale A locale code for the locale format rules to use. + * @param width The format type. + * @returns The localized formatting string. + * @see `FormatWidth` + * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n) * * @publicApi */ @@ -313,8 +380,12 @@ export function getLocaleDateTimeFormat(locale: string, width: FormatWidth): str } /** - * Number symbol that can be used to replace placeholders in number formats. - * See {@link NumberSymbol} for more information. + * Retrieves a localized number symbol that can be used to replace placeholders in number formats. + * @param locale The locale code. + * @param symbol The symbol to localize. + * @returns The character for the localized symbol. + * @see `NumberSymbol` + * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n) * * @publicApi */ @@ -332,17 +403,17 @@ export function getLocaleNumberSymbol(locale: string, symbol: NumberSymbol): str } /** - * Number format that depends on the locale. + * Retrieves a number format for a given locale. * * Numbers are formatted using patterns, like `#,###.00`. For example, the pattern `#,###.00` - * when used to format the number 12345.678 could result in "12'345,67". That would happen if the + * when used to format the number 12345.678 could result in "12'345,678". That would happen if the * grouping separator for your language is an apostrophe, and the decimal separator is a comma. * - * Important: The characters `.` `,` `0` `#` (and others below) are special placeholders; - * they stand for the decimal separator, and so on, and are NOT real characters. - * You must NOT "translate" the placeholders; for example, don't change `.` to `,` even though in + * Important: The characters `.` `,` `0` `#` (and others below) are special placeholders + * that stand for the decimal separator, and so on, and are NOT real characters. + * You must NOT "translate" the placeholders. For example, don't change `.` to `,` even though in * your language the decimal point is written with a comma. The symbols should be replaced by the - * local equivalents, using the Number Symbols for your language. + * local equivalents, using the appropriate `NumberSymbol` for your language. * * Here are the special characters used in number patterns: * @@ -352,13 +423,17 @@ export function getLocaleNumberSymbol(locale: string, symbol: NumberSymbol): str * | , | Replaced by the "grouping" (thousands) separator. | * | 0 | Replaced by a digit (or zero if there aren't enough digits). | * | # | Replaced by a digit (or nothing if there aren't enough). | - * | ¤ | This will be replaced by a currency symbol, such as $ or USD. | - * | % | This marks a percent format. The % symbol may change position, but must be retained. | - * | E | This marks a scientific format. The E symbol may change position, but must be retained. | + * | ¤ | Replaced by a currency symbol, such as $ or USD. | + * | % | Marks a percent format. The % symbol may change position, but must be retained. | + * | E | Marks a scientific format. The E symbol may change position, but must be retained. | * | ' | Special characters used as literal characters are quoted with ASCII single quotes. | * - * You can find more information - * [on the CLDR website](http://cldr.unicode.org/translation/number-patterns) + * @param locale A locale code for the locale format rules to use. + * @param type The type of numeric value to be formatted (such as `Decimal` or `Currency`.) + * @returns The localized format string. + * @see `NumberFormatStyle` + * @see [CLDR website](http://cldr.unicode.org/translation/number-patterns) + * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n) * * @publicApi */ @@ -368,9 +443,13 @@ export function getLocaleNumberFormat(locale: string, type: NumberFormatStyle): } /** - * The symbol used to represent the currency for the main country using this locale (e.g. $ for - * the locale en-US). - * The symbol will be `null` if the main country cannot be determined. + * Retrieves the symbol used to represent the currency for the main country + * corresponding to a given locale. For example, '$' for `en-US`. + * + * @param locale A locale code for the locale format rules to use. + * @returns The localized symbol character, + * or `null` if the main country cannot be determined. + * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n) * * @publicApi */ @@ -380,9 +459,12 @@ export function getLocaleCurrencySymbol(locale: string): string|null { } /** - * The name of the currency for the main country using this locale (e.g. 'US Dollar' for the locale - * en-US). - * The name will be `null` if the main country cannot be determined. + * Retrieves the name of the currency for the main country corresponding + * to a given locale. For example, 'US Dollar' for `en-US`. + * @param locale A locale code for the locale format rules to use. + * @returns The currency name, + * or `null` if the main country cannot be determined. + * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n) * * @publicApi */ @@ -392,7 +474,10 @@ export function getLocaleCurrencyName(locale: string): string|null { } /** - * Returns the currency values for the locale + * Retrieves the currency values for a given locale. + * @param locale A locale code for the locale format rules to use. + * @returns The currency values. + * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n) */ function getLocaleCurrencies(locale: string): {[code: string]: CurrenciesSymbols} { const data = findLocaleData(locale); @@ -400,8 +485,12 @@ function getLocaleCurrencies(locale: string): {[code: string]: CurrenciesSymbols } /** - * The locale plural function used by ICU expressions to determine the plural case to use. - * See {@link NgPlural} for more information. + * Retrieves the plural function used by ICU expressions to determine the plural case to use + * for a given locale. + * @param locale A locale code for the locale format rules to use. + * @returns The plural function for the locale. + * @see `NgPlural` + * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n) * * @publicApi */ @@ -418,17 +507,24 @@ function checkFullData(data: any) { } /** - * Rules used to determine which day period to use (See `dayPeriods` below). - * The rules can either be an array or a single value. If it's an array, consider it as "from" - * and "to". If it's a single value then it means that the period is only valid at this exact - * value. - * There is always the same number of rules as the number of day periods, which means that the - * first rule is applied to the first day period and so on. - * You should fallback to AM/PM when there are no rules available. + * Retrieves locale-specific rules used to determine which day period to use + * when more than one period is defined for a locale. * - * Note: this is only available if you load the full locale data. - * See the ["I18n guide"](guide/i18n#i18n-pipes) to know how to import additional locale - * data. + * There is a rule for each defined day period. The + * first rule is applied to the first day period and so on. + * Fall back to AM/PM when no rules are available. + * + * A rule can specify a period as time range, or as a single time value. + * + * This functionality is only available when you have loaded the full locale data. + * See the ["I18n guide"](guide/i18n#i18n-pipes). + * + * @param locale A locale code for the locale format rules to use. + * @returns The rules for the locale, a single time value or array of *from-time, to-time*, + * or null if no periods are available. + * + * @see `getLocaleExtraDayPeriods()` + * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n) * * @publicApi */ @@ -445,15 +541,19 @@ export function getLocaleExtraDayPeriodRules(locale: string): (Time | [Time, Tim } /** - * Day Periods indicate roughly how the day is broken up in different languages (e.g. morning, - * noon, afternoon, midnight, ...). - * You should use the function {@link getLocaleExtraDayPeriodRules} to determine which period to - * use. - * You should fallback to AM/PM when there are no day periods available. + * Retrieves locale-specific day periods, which indicate roughly how a day is broken up + * in different languages. + * For example, for `en-US`, periods are morning, noon, afternoon, evening, and midnight. * - * Note: this is only available if you load the full locale data. - * See the ["I18n guide"](guide/i18n#i18n-pipes) to know how to import additional locale - * data. + * This functionality is only available when you have loaded the full locale data. + * See the ["I18n guide"](guide/i18n#i18n-pipes). + * + * @param locale A locale code for the locale format rules to use. + * @param formStyle The required grammatical form. + * @param width The required character width. + * @returns The translated day-period strings. + * @see `getLocaleExtraDayPeriodRules()` + * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n) * * @publicApi */ @@ -470,11 +570,15 @@ export function getLocaleExtraDayPeriods( } /** - * Returns the first value that is defined in an array, going backwards. + * Retrieves the first value that is defined in an array, going backwards from an index position. * - * To avoid repeating the same data (e.g. when "format" and "standalone" are the same) we only - * add the first one to the locale data arrays, the other ones are only defined when different. - * We use this function to retrieve the first defined value. + * To avoid repeating the same data (as when the "format" and "standalone" forms are the same) + * add the first value to the locale data arrays, and add other values only if they are different. + * + * @param data The data array to retrieve from. + * @param index A 0-based index into the array to start from. + * @returns The value immediately before the given index position. + * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n) * * @publicApi */ @@ -488,7 +592,7 @@ function getLastDefinedValue(data: T[], index: number): T { } /** - * A representation of the time with hours and minutes + * Represents a time value with hours and minutes. * * @publicApi */ @@ -498,7 +602,7 @@ export type Time = { }; /** - * Extract the hours and minutes from a string like "15:45" + * Extracts the hours and minutes from a string like "15:45" */ function extractTime(time: string): Time { const [h, m] = time.split(':'); @@ -506,7 +610,11 @@ function extractTime(time: string): Time { } /** - * Finds the locale data for a locale id + * Finds the locale data for a given locale. + * + * @param locale The locale code. + * @returns The locale data. + * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n) * * @publicApi */ @@ -534,9 +642,17 @@ export function findLocaleData(locale: string): any { } /** - * Returns the currency symbol for a given currency code, or the code if no symbol available - * (e.g.: format narrow = $, format wide = US$, code = USD) - * If no locale is provided, it uses the locale "en" by default + * Retrieves the currency symbol for a given currency code. + * + * For example, for the default `en-US` locale, the code `USD` can + * be represented by the narrow symbol `$` or the wide symbol `US$`. + * + * @param code The currency code. + * @param format The format, `wide` or `narrow`. + * @param locale A locale code for the locale format rules to use. + * + * @returns The symbol, or the currency code if no symbol is available.0 + * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n) * * @publicApi */ @@ -555,8 +671,12 @@ export function getCurrencySymbol(code: string, format: 'wide' | 'narrow', local const DEFAULT_NB_OF_CURRENCY_DIGITS = 2; /** - * Returns the number of decimal digits for the given currency. - * Its value depends upon the presence of cents in that particular currency. + * Reports the number of decimal digits for a given currency. + * The value depends upon the presence of cents in that particular currency. + * + * @param code The currency code. + * @returns The number of decimal digits, typically 0 or 2. + * @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n) * * @publicApi */ diff --git a/packages/core/src/di/injector_compatibility.ts b/packages/core/src/di/injector_compatibility.ts index f314afce57..6ff623c3e6 100644 --- a/packages/core/src/di/injector_compatibility.ts +++ b/packages/core/src/di/injector_compatibility.ts @@ -70,18 +70,24 @@ export function injectInjectorOnly( /** * Injects a token from the currently active injector. + * Must be used in the context of a factory function such as one defined for an + * `InjectionToken`. Throws an error if not called from such a context. * - * This function must be used in the context of a factory function such as one defined for an - * `InjectionToken`, and will throw an error if not called from such a context. + * Within such a factory function, using this function to request injection of a dependency + * is faster and more type-safe than providing an additional array of dependencies + * (as has been common with `useFactory` providers). + * + * @param token The injection token for the dependency to be injected. + * @param flags Optional flags that control how injection is executed. + * The flags correspond to injection strategies that can be specified with + * parameter decorators `@Host`, `@Self`, `@SkipSef`, and `@Optional`. + * @returns True if injection is successful, null otherwise. * * @usageNotes + * * ### Example * - * {@example core/di/ts/injector_spec.ts region='ShakeableInjectionToken'} - * - * Within such a factory function `inject` is utilized to request injection of a dependency, instead - * of providing an additional array of dependencies as was common to do with `useFactory` providers. - * `inject` is faster and more type-safe. + * {@example core/di/ts/injector_spec.ts region='ShakableInjectionToken'} * * @publicApi */