docs(common): move Pipe param docs to transform function (#23062)

PR Close #23062

Author: petebacondarwin

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;
 

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 '';
 

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 '';
 

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: <br>
- *     <code>{minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}</code>.
- *   - `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: <br>
+   * <code>{minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}</code>.
+   *   - `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,

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;