From cdd05bd2ca5733e99c7682b20c7283570c70e671 Mon Sep 17 00:00:00 2001 From: Pete Bacon Darwin Date: Thu, 29 Mar 2018 17:04:47 +0100 Subject: [PATCH] docs(common): move Pipe param docs to `transform` function (#23062) PR Close #23062 --- packages/common/src/pipes/date_pipe.ts | 48 +++++++------- packages/common/src/pipes/i18n_plural_pipe.ts | 14 ++-- packages/common/src/pipes/i18n_select_pipe.ts | 15 +++-- packages/common/src/pipes/number_pipe.ts | 66 ++++++++++--------- packages/common/src/pipes/slice_pipe.ts | 33 +++++----- 5 files changed, 91 insertions(+), 85 deletions(-) diff --git a/packages/common/src/pipes/date_pipe.ts b/packages/common/src/pipes/date_pipe.ts index 821b7dd0fe..0fad70a4d5 100644 --- a/packages/common/src/pipes/date_pipe.ts +++ b/packages/common/src/pipes/date_pipe.ts @@ -17,30 +17,7 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error'; * * Uses the function {@link formatDate} to format a date according to locale rules. * - * Where: - * - `value` is a date object or 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. The format can be predefined as - * shown below (all examples are given for `en-US`) or custom as shown in the table. - * - `'short'`: equivalent to `'M/d/yy, h:mm a'` (e.g. `6/15/15, 9:03 AM`). - * - `'medium'`: equivalent to `'MMM d, y, h:mm:ss a'` (e.g. `Jun 15, 2015, 9:03:01 AM`). - * - `'long'`: equivalent to `'MMMM d, y, h:mm:ss a z'` (e.g. `June 15, 2015 at 9:03:01 AM GMT+1`). - * - `'full'`: equivalent to `'EEEE, MMMM d, y, h:mm:ss a zzzz'` (e.g. `Monday, June 15, 2015 at - * 9:03:01 AM GMT+01:00`). - * - `'shortDate'`: equivalent to `'M/d/yy'` (e.g. `6/15/15`). - * - `'mediumDate'`: equivalent to `'MMM d, y'` (e.g. `Jun 15, 2015`). - * - `'longDate'`: equivalent to `'MMMM d, y'` (e.g. `June 15, 2015`). - * - `'fullDate'`: equivalent to `'EEEE, MMMM d, y'` (e.g. `Monday, June 15, 2015`). - * - `'shortTime'`: equivalent to `'h:mm a'` (e.g. `9:03 AM`). - * - `'mediumTime'`: equivalent to `'h:mm:ss a'` (e.g. `9:03:01 AM`). - * - `'longTime'`: equivalent to `'h:mm:ss a z'` (e.g. `9:03:01 AM GMT+1`). - * - `'fullTime'`: equivalent to `'h:mm:ss a zzzz'` (e.g. `9:03:01 AM GMT+01:00`). - * - `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, the local system timezone of the end-user's browser will be used. - * - `locale` is a `string` defining the locale to use (uses the current {@link LOCALE_ID} by - * default). - * + * The following tabled describes the formatting options. * * | Field Type | Format | Description | Example Value | * |--------------------|-------------|---------------------------------------------------------------|------------------------------------------------------------| @@ -129,6 +106,29 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error'; export class DatePipe implements PipeTransform { constructor(@Inject(LOCALE_ID) private locale: string) {} + /** + * @param value a date object or a number (milliseconds since UTC epoch) or an ISO string + * (https://www.w3.org/TR/NOTE-datetime). + * @param format indicates which date/time components to include. The format can be predefined as + * shown below (all examples are given for `en-US`) or custom as shown in the table. + * - `'short'`: equivalent to `'M/d/yy, h:mm a'` (e.g. `6/15/15, 9:03 AM`). + * - `'medium'`: equivalent to `'MMM d, y, h:mm:ss a'` (e.g. `Jun 15, 2015, 9:03:01 AM`). + * - `'long'`: equivalent to `'MMMM d, y, h:mm:ss a z'` (e.g. `June 15, 2015 at 9:03:01 AM GMT+1`). + * - `'full'`: equivalent to `'EEEE, MMMM d, y, h:mm:ss a zzzz'` (e.g. `Monday, June 15, 2015 at + * 9:03:01 AM GMT+01:00`). + * - `'shortDate'`: equivalent to `'M/d/yy'` (e.g. `6/15/15`). + * - `'mediumDate'`: equivalent to `'MMM d, y'` (e.g. `Jun 15, 2015`). + * - `'longDate'`: equivalent to `'MMMM d, y'` (e.g. `June 15, 2015`). + * - `'fullDate'`: equivalent to `'EEEE, MMMM d, y'` (e.g. `Monday, June 15, 2015`). + * - `'shortTime'`: equivalent to `'h:mm a'` (e.g. `9:03 AM`). + * - `'mediumTime'`: equivalent to `'h:mm:ss a'` (e.g. `9:03:01 AM`). + * - `'longTime'`: equivalent to `'h:mm:ss a z'` (e.g. `9:03:01 AM GMT+1`). + * - `'fullTime'`: equivalent to `'h:mm:ss a zzzz'` (e.g. `9:03:01 AM GMT+01:00`). + * @param timezone to be used for formatting the time. It understands UTC/GMT and the continental US time zone + * abbreviations, but for general use, use a time zone offset (e.g. `'+0430'`). + * @param locale a `string` defining the locale to use (uses the current {@link LOCALE_ID} by + * default). + */ transform(value: any, format = 'mediumDate', timezone?: string, locale?: string): string|null { if (value == null || value === '' || value !== value) return null; diff --git a/packages/common/src/pipes/i18n_plural_pipe.ts b/packages/common/src/pipes/i18n_plural_pipe.ts index 80d08d4492..2ed3eb5138 100644 --- a/packages/common/src/pipes/i18n_plural_pipe.ts +++ b/packages/common/src/pipes/i18n_plural_pipe.ts @@ -18,13 +18,6 @@ const _INTERPOLATION_REGEXP: RegExp = /#/g; * * Maps a value to a string that pluralizes the value according to locale rules. * - * Where: - * - `expression` is a number. - * - `mapping` is an object that mimics the ICU format, see - * http://userguide.icu-project.org/formatparse/messages - * - `locale` is a `string` defining the locale to use (uses the current {@link LOCALE_ID} by - * default) - * * ## Example * * {@example common/pipes/ts/i18n_pipe.ts region='I18nPluralPipeComponent'} @@ -35,6 +28,13 @@ const _INTERPOLATION_REGEXP: RegExp = /#/g; export class I18nPluralPipe implements PipeTransform { constructor(private _localization: NgLocalization) {} + /** + * @param value the number to be formatted + * @param pluralMap an object that mimics the ICU format, see + * http://userguide.icu-project.org/formatparse/messages. + * @param locale a `string` defining the locale to use (uses the current {@link LOCALE_ID} by + * default). + */ transform(value: number, pluralMap: {[count: string]: string}, locale?: string): string { if (value == null) return ''; diff --git a/packages/common/src/pipes/i18n_select_pipe.ts b/packages/common/src/pipes/i18n_select_pipe.ts index 2ab7449b29..0ff8460d01 100644 --- a/packages/common/src/pipes/i18n_select_pipe.ts +++ b/packages/common/src/pipes/i18n_select_pipe.ts @@ -15,19 +15,22 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error'; * * Generic selector that displays the string that matches the current value. * - * Where `mapping` is an object that indicates the text that should be displayed - * for different values of the provided `expression`. - * If none of the keys of the mapping match the value of the `expression`, then the content - * of the `other` key is returned when present, otherwise an empty string is returned. + * If none of the keys of the `mapping` match the `value`, then the content + * of the `other` key is returned when present, otherwise an empty string is returned. * - * ## Example + * ## Example * * {@example common/pipes/ts/i18n_pipe.ts region='I18nSelectPipeComponent'} * - * @experimental + * @experimental */ @Pipe({name: 'i18nSelect', pure: true}) export class I18nSelectPipe implements PipeTransform { + /** + * @param value a string to be internationalized. + * @param mapping an object that indicates the text that should be displayed + * for different values of the provided `value`. + */ transform(value: string|null|undefined, mapping: {[key: string]: string}): string { if (value == null) return ''; diff --git a/packages/common/src/pipes/number_pipe.ts b/packages/common/src/pipes/number_pipe.ts index e9b47d49aa..e29df041d8 100644 --- a/packages/common/src/pipes/number_pipe.ts +++ b/packages/common/src/pipes/number_pipe.ts @@ -20,16 +20,6 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error'; * Formats a number as text. Group sizing and separator and other locale-specific * configurations are based on the locale. * - * Where: - * - `value` is a number - * - `digitInfo` is a `string` which has a following format:
- * {minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}. - * - `minIntegerDigits` is the minimum number of integer digits to use. Defaults to `1`. - * - `minFractionDigits` is the minimum number of digits after the decimal point. Defaults to `0`. - * - `maxFractionDigits` is the maximum number of digits after the decimal point. Defaults to `3`. - * - `locale` is a `string` defining the locale to use (uses the current {@link LOCALE_ID} by - * default). - * * ### Example * * {@example common/pipes/ts/number_pipe.ts region='NumberPipe'} @@ -40,6 +30,16 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error'; export class DecimalPipe implements PipeTransform { constructor(@Inject(LOCALE_ID) private _locale: string) {} + /** + * @param value a number to be formatted. + * @param digitsInfo a `string` which has a following format:
+ * {minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}. + * - `minIntegerDigits` is the minimum number of integer digits to use. Defaults to `1`. + * - `minFractionDigits` is the minimum number of digits after the decimal point. Defaults to `0`. + * - `maxFractionDigits` is the maximum number of digits after the decimal point. Defaults to `3`. + * @param locale a `string` defining the locale to use (uses the current {@link LOCALE_ID} by + * default). + */ transform(value: any, digitsInfo?: string, locale?: string): string|null { if (isEmpty(value)) return null; @@ -61,12 +61,6 @@ export class DecimalPipe implements PipeTransform { * Uses the function {@link formatPercent} to format a number as a percentage according * to locale rules. * - * Where: - * - `value` is a number. - * - `digitInfo` See {@link DecimalPipe} for more details. - * - `locale` is a `string` defining the locale to use (uses the current {@link LOCALE_ID} by - * default). - * * ### Example * * {@example common/pipes/ts/percent_pipe.ts region='PercentPipe'} @@ -77,6 +71,13 @@ export class DecimalPipe implements PipeTransform { export class PercentPipe implements PipeTransform { constructor(@Inject(LOCALE_ID) private _locale: string) {} + /** + * + * @param value a number to be formatted as a percentage. + * @param digitsInfo see {@link DecimalPipe} for more details. + * @param locale a `string` defining the locale to use (uses the current {@link LOCALE_ID} by + * default). + */ transform(value: any, digitsInfo?: string, locale?: string): string|null { if (isEmpty(value)) return null; @@ -98,22 +99,6 @@ export class PercentPipe implements PipeTransform { * Uses the functions {@link getCurrencySymbol} and {@link formatCurrency} to format a * number as currency using locale rules. * - * Where: - * - `value` is a number. - * - `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. - * - `display` indicates whether to show the currency symbol, the code or a custom value: - * - `code`: use code (e.g. `USD`). - * - `symbol`(default): use symbol (e.g. `$`). - * - `symbol-narrow`: some countries have two symbols for their currency, one regular and one - * narrow (e.g. the canadian dollar CAD has the symbol `CA$` and the symbol-narrow `$`). - * - `string`: use this value instead of a code or a symbol. - * - boolean (deprecated from v5): `true` for symbol and false for `code`. - * If there is no narrow symbol for the chosen currency, the regular symbol will be used. - * - `digitInfo` See {@link DecimalPipe} for more details. - * - `locale` is a `string` defining the locale to use (uses the current {@link LOCALE_ID} by - * default). - * * ### Example * * {@example common/pipes/ts/currency_pipe.ts region='CurrencyPipe'} @@ -124,6 +109,23 @@ export class PercentPipe implements PipeTransform { export class CurrencyPipe implements PipeTransform { constructor(@Inject(LOCALE_ID) private _locale: string) {} + /** + * + * @param value a number to be formatted as currency. + * @param currencyCodeis the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code, such + * as `USD` for the US dollar and `EUR` for the euro. + * @param display indicates whether to show the currency symbol, the code or a custom value: + * - `code`: use code (e.g. `USD`). + * - `symbol`(default): use symbol (e.g. `$`). + * - `symbol-narrow`: some countries have two symbols for their currency, one regular and one + * narrow (e.g. the canadian dollar CAD has the symbol `CA$` and the symbol-narrow `$`). + * - `string`: use this value instead of a code or a symbol. + * - boolean (deprecated from v5): `true` for symbol and false for `code`. + * If there is no narrow symbol for the chosen currency, the regular symbol will be used. + * @param digitsInfo see {@link DecimalPipe} for more details. + * @param locale a `string` defining the locale to use (uses the current {@link LOCALE_ID} by + * default). + */ transform( value: any, currencyCode?: string, display: 'code'|'symbol'|'symbol-narrow'|string|boolean = 'symbol', digitsInfo?: string, diff --git a/packages/common/src/pipes/slice_pipe.ts b/packages/common/src/pipes/slice_pipe.ts index c0780866ca..d587190cbb 100644 --- a/packages/common/src/pipes/slice_pipe.ts +++ b/packages/common/src/pipes/slice_pipe.ts @@ -13,30 +13,17 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error'; * @ngModule CommonModule * @description * - * Creates a new List or String containing a subset (slice) of the elements. - * - * Where the input expression is a `List` or `String`, and: - * - `start`: The starting index of the subset to return. - * - **a positive integer**: return the item at `start` index and all items after - * in the list or string expression. - * - **a negative integer**: return the item at `start` index from the end and all items after - * in the list or string expression. - * - **if positive and greater than the size of the expression**: return an empty list or string. - * - **if negative and greater than the size of the expression**: return entire list or string. - * - `end`: The ending index of the subset to return. - * - **omitted**: return all items until the end. - * - **if positive**: return all items before `end` index of the list or string. - * - **if negative**: return all items before `end` index from the end of the list or string. + * Creates a new `Array` or `String` containing a subset (slice) of the elements. * * All behavior is based on the expected behavior of the JavaScript API `Array.prototype.slice()` * and `String.prototype.slice()`. * - * When operating on a [List], the returned list is always a copy even when all + * When operating on an `Array`, the returned `Array` is always a copy even when all * the elements are being returned. * * When operating on a blank value, the pipe returns the blank value. * - * ## List Example + * ### List Example * * This `ngFor` example: * @@ -56,6 +43,20 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error'; @Pipe({name: 'slice', pure: false}) export class SlicePipe implements PipeTransform { + /** + * @param value a list or a string to be sliced. + * @param start the starting index of the subset to return: + * - **a positive integer**: return the item at `start` index and all items after + * in the list or string expression. + * - **a negative integer**: return the item at `start` index from the end and all items after + * in the list or string expression. + * - **if positive and greater than the size of the expression**: return an empty list or string. + * - **if negative and greater than the size of the expression**: return entire list or string. + * @param end the ending index of the subset to return: + * - **omitted**: return all items until the end. + * - **if positive**: return all items before `end` index of the list or string. + * - **if negative**: return all items before `end` index from the end of the list or string. + */ transform(value: any, start: number, end?: number): any { if (value == null) return value;