Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add API doc for pipes/i18n config #29289

Closed
wants to merge 1 commit into from
Closed

Add API doc for pipes/i18n config #29289

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
21 changes: 11 additions & 10 deletions packages/common/src/i18n/format_date.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Time zone abbreviation doesn't seem to be supported: #20225

* 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
*/
Expand Down
53 changes: 34 additions & 19 deletions packages/common/src/i18n/format_number.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe add a link to the locale section in the i18n guide here?
Also you should have the same description for all locale params of all of those functions. Right now the description is different but it's talking about the same thing. For example for formatDate it says @param locale The locale code..

* @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
*/
Expand All @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same comments as above

* @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);
Expand All @@ -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.
*
* @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.
*
* Where:
* - `value` is a number.
* - `locale` is a `string` defining the locale to use.
* - `digitInfo` See {@link DecimalPipe} for more details.
* @returns The formatted text string.
* @see [Internationalization (i18n) Guide](https://angular.io/guide/i18n)
*
* @publicApi
*/
Expand Down