diff --git a/aio/tools/transforms/templates/api/lib/paramList.html b/aio/tools/transforms/templates/api/lib/paramList.html index 10fb182c84fb6..0f63ad32d9eb9 100644 --- a/aio/tools/transforms/templates/api/lib/paramList.html +++ b/aio/tools/transforms/templates/api/lib/paramList.html @@ -21,11 +21,12 @@ {% if showType %}{$ parameter.type $}{% endif %} {% marked %} - {% if parameter.isOptional or parameter.defaultValue !== undefined %}Optional. Default is `{$ parameter.defaultValue === undefined and 'undefined' or parameter.defaultValue $}`.{% endif %} + {% if parameter.description | trim %}{$ parameter.description $} - {% if parameter.description | trim %}{$ parameter.description $} - {% elseif not showType and parameter.type %}

Type: {$ parameter.type $}.

- {% endif %} + {% elseif not showType and parameter.type %}

Type: {$ parameter.type $}.

+ {% endif %} + + {% if parameter.isOptional or parameter.defaultValue !== undefined %}Optional. Default is `{$ parameter.defaultValue === undefined and 'undefined' or parameter.defaultValue $}`.{% endif %} {% endmarked %} {% endfor %} diff --git a/packages/common/src/directives/ng_class.ts b/packages/common/src/directives/ng_class.ts index 9acc430fde067..2a17cf5ae0e72 100644 --- a/packages/common/src/directives/ng_class.ts +++ b/packages/common/src/directives/ng_class.ts @@ -11,9 +11,7 @@ import {Directive, DoCheck, ElementRef, Input, IterableChanges, IterableDiffer, /** * @ngModule CommonModule * - * @whatItDoes Adds and removes CSS classes on an HTML element. - * - * @howToUse + * @usageNotes * ``` * ... * @@ -28,6 +26,8 @@ import {Directive, DoCheck, ElementRef, Input, IterableChanges, IterableDiffer, * * @description * + * Adds and removes CSS classes on an HTML element. + * * The CSS classes are updated as follows, depending on the type of the expression evaluation: * - `string` - the CSS classes listed in the string (space delimited) are added, * - `Array` - the CSS classes declared as Array elements are added, diff --git a/packages/common/src/directives/ng_plural.ts b/packages/common/src/directives/ng_plural.ts index f82479aa5f4b0..cdf13c83747f7 100644 --- a/packages/common/src/directives/ng_plural.ts +++ b/packages/common/src/directives/ng_plural.ts @@ -16,9 +16,7 @@ import {SwitchView} from './ng_switch'; /** * @ngModule CommonModule * - * @whatItDoes Adds / removes DOM sub-trees based on a numeric value. Tailored for pluralization. - * - * @howToUse + * @usageNotes * ``` * * there is nothing @@ -29,6 +27,8 @@ import {SwitchView} from './ng_switch'; * * @description * + * Adds / removes DOM sub-trees based on a numeric value. Tailored for pluralization. + * * Displays DOM sub-trees that match the switch expression value, or failing that, DOM sub-trees * that match the switch expression's pluralization category. * @@ -83,10 +83,12 @@ export class NgPlural { /** * @ngModule CommonModule * - * @whatItDoes Creates a view that will be added/removed from the parent {@link NgPlural} when the - * given expression matches the plural expression according to CLDR rules. + * @description + * + * Creates a view that will be added/removed from the parent {@link NgPlural} when the + * given expression matches the plural expression according to CLDR rules. * - * @howToUse + * @usageNotes * ``` * * ... diff --git a/packages/common/src/directives/ng_style.ts b/packages/common/src/directives/ng_style.ts index d048f9774d004..504021f7bcbba 100644 --- a/packages/common/src/directives/ng_style.ts +++ b/packages/common/src/directives/ng_style.ts @@ -11,9 +11,7 @@ import {Directive, DoCheck, ElementRef, Input, KeyValueChanges, KeyValueDiffer, /** * @ngModule CommonModule * - * @whatItDoes Update an HTML element styles. - * - * @howToUse + * @usageNotes * ``` * ... * @@ -24,6 +22,8 @@ import {Directive, DoCheck, ElementRef, Input, KeyValueChanges, KeyValueDiffer, * * @description * + * Update an HTML element styles. + * * The styles are updated according to the value of the expression evaluation: * - keys are style names with an optional `.` suffix (ie 'top.px', 'font-style.em'), * - values are the values assigned to those properties (expressed in the given unit). diff --git a/packages/common/src/directives/ng_switch.ts b/packages/common/src/directives/ng_switch.ts index 1e7f10d8ff09e..000e0ffbae61a 100644 --- a/packages/common/src/directives/ng_switch.ts +++ b/packages/common/src/directives/ng_switch.ts @@ -36,10 +36,7 @@ export class SwitchView { /** * @ngModule CommonModule * - * @whatItDoes Adds / removes DOM sub-trees when the nest match expressions matches the switch - * expression. - * - * @howToUse + * @usageNotes * ``` * * ... @@ -55,6 +52,8 @@ export class SwitchView { * ``` * @description * + * Adds / removes DOM sub-trees when the nest match expressions matches the switch expression. + * * `NgSwitch` stamps out nested views when their match expression value matches the value of the * switch expression. * @@ -129,11 +128,7 @@ export class NgSwitch { /** * @ngModule CommonModule * - * @whatItDoes Creates a view that will be added/removed from the parent {@link NgSwitch} when the - * given expression evaluate to respectively the same/different value as the switch - * expression. - * - * @howToUse + * @usageNotes * ``` * * ... @@ -141,6 +136,10 @@ export class NgSwitch { *``` * @description * + * Creates a view that will be added/removed from the parent {@link NgSwitch} when the + * given expression evaluate to respectively the same/different value as the switch + * expression. + * * Insert the sub-tree when the expression evaluates to the same value as the enclosing switch * expression. * @@ -169,11 +168,7 @@ export class NgSwitchCase implements DoCheck { /** * @ngModule CommonModule - * @whatItDoes Creates a view that is added to the parent {@link NgSwitch} when no case expressions - * match the - * switch expression. - * - * @howToUse + * @usageNotes * ``` * * ... @@ -183,6 +178,9 @@ export class NgSwitchCase implements DoCheck { * * @description * + * Creates a view that is added to the parent {@link NgSwitch} when no case expressions + * match the switch expression. + * * Insert the sub-tree when no case expressions evaluate to the same value as the enclosing switch * expression. * diff --git a/packages/common/src/directives/ng_template_outlet.ts b/packages/common/src/directives/ng_template_outlet.ts index f653503b62ac9..c76668ab1443c 100644 --- a/packages/common/src/directives/ng_template_outlet.ts +++ b/packages/common/src/directives/ng_template_outlet.ts @@ -11,15 +11,15 @@ import {Directive, EmbeddedViewRef, Input, OnChanges, SimpleChange, SimpleChange /** * @ngModule CommonModule * - * @whatItDoes Inserts an embedded view from a prepared `TemplateRef` - * - * @howToUse + * @usageNotes * ``` * * ``` * * @description * + * Inserts an embedded view from a prepared `TemplateRef`. + * * You can attach a context object to the `EmbeddedViewRef` by setting `[ngTemplateOutletContext]`. * `[ngTemplateOutletContext]` should be an object, the object's keys will be available for binding * by the local template `let` declarations. diff --git a/packages/common/src/i18n/format_date.ts b/packages/common/src/i18n/format_date.ts index 981257ecb7486..78015bf26fb07 100644 --- a/packages/common/src/i18n/format_date.ts +++ b/packages/common/src/i18n/format_date.ts @@ -42,9 +42,10 @@ enum TranslationType { /** * @ngModule CommonModule - * @whatItDoes Formats a date according to locale rules. * @description * + * 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). diff --git a/packages/common/src/i18n/format_number.ts b/packages/common/src/i18n/format_number.ts index 4f31086881a92..b2c4876141b85 100644 --- a/packages/common/src/i18n/format_number.ts +++ b/packages/common/src/i18n/format_number.ts @@ -124,9 +124,10 @@ function formatNumberToLocaleString( /** * @ngModule CommonModule - * @whatItDoes Formats a number as currency using locale rules. * @description * + * Formats a number as currency using locale rules. + * * Use `currency` to format a number as currency. * * Where: @@ -158,10 +159,9 @@ export function formatCurrency( /** * @ngModule CommonModule - * @whatItDoes Formats a number as a percentage according to locale rules. * @description * - * Formats a number as percentage. + * Formats a number as a percentage according to locale rules. * * Where: * - `value` is a number. @@ -181,7 +181,6 @@ export function formatPercent(value: number, locale: string, digitsInfo?: string /** * @ngModule CommonModule - * @whatItDoes Formats a number according to locale rules. * @description * * Formats a number as text. Group sizing and separator and other locale-specific diff --git a/packages/common/src/location/hash_location_strategy.ts b/packages/common/src/location/hash_location_strategy.ts index 70bd23256e8d1..1fe05f007e1a3 100644 --- a/packages/common/src/location/hash_location_strategy.ts +++ b/packages/common/src/location/hash_location_strategy.ts @@ -16,10 +16,9 @@ import {LocationChangeListener, PlatformLocation} from './platform_location'; /** - * @whatItDoes Use URL hash for storing application location data. * @description - * `HashLocationStrategy` is a {@link LocationStrategy} used to configure the - * {@link Location} service to represent its state in the + * A {@link LocationStrategy} used to configure the {@link Location} service to + * represent its state in the * [hash fragment](https://en.wikipedia.org/wiki/Uniform_Resource_Locator#Syntax) * of the browser's URL. * diff --git a/packages/common/src/location/location.ts b/packages/common/src/location/location.ts index dfd07858a8e49..ce5a6d0f3eac5 100644 --- a/packages/common/src/location/location.ts +++ b/packages/common/src/location/location.ts @@ -20,8 +20,10 @@ export interface PopStateEvent { } /** - * @whatItDoes `Location` is a service that applications can use to interact with a browser's URL. * @description + * + * A service that applications can use to interact with a browser's URL. + * * Depending on which {@link LocationStrategy} is used, `Location` will either persist * to the URL's path or the URL's hash segment. * diff --git a/packages/common/src/location/path_location_strategy.ts b/packages/common/src/location/path_location_strategy.ts index d3ccf7ecfe05b..3854ec8bf05e0 100644 --- a/packages/common/src/location/path_location_strategy.ts +++ b/packages/common/src/location/path_location_strategy.ts @@ -16,10 +16,9 @@ import {LocationChangeListener, PlatformLocation} from './platform_location'; /** - * @whatItDoes Use URL for storing application location data. * @description - * `PathLocationStrategy` is a {@link LocationStrategy} used to configure the - * {@link Location} service to represent its state in the + * A {@link LocationStrategy} used to configure the {@link Location} service to + * represent its state in the * [path](https://en.wikipedia.org/wiki/Uniform_Resource_Locator#Syntax) of the * browser's URL. * diff --git a/packages/common/src/location/platform_location.ts b/packages/common/src/location/platform_location.ts index 177b6a474a538..c222a3a75afba 100644 --- a/packages/common/src/location/platform_location.ts +++ b/packages/common/src/location/platform_location.ts @@ -48,13 +48,14 @@ export abstract class PlatformLocation { } /** - * @whatItDoes indicates when a location is initialized + * @description Indicates when a location is initialized. * @experimental */ export const LOCATION_INITIALIZED = new InjectionToken>('Location Initialized'); /** - * A serializable version of the event from onPopState or onHashChange + * @description + * A serializable version of the event from `onPopState` or `onHashChange` * * @experimental */ diff --git a/packages/common/src/pipes/async_pipe.ts b/packages/common/src/pipes/async_pipe.ts index 1332251df197b..1167ae7524396 100644 --- a/packages/common/src/pipes/async_pipe.ts +++ b/packages/common/src/pipes/async_pipe.ts @@ -42,9 +42,10 @@ const _observableStrategy = new ObservableStrategy(); /** * @ngModule CommonModule - * @whatItDoes Unwraps a value from an asynchronous primitive. - * @howToUse `observable_or_promise_expression | async` * @description + * + * Unwraps a value from an asynchronous primitive. + * * The `async` pipe subscribes to an `Observable` or `Promise` and returns the latest value it has * emitted. When a new value is emitted, the `async` pipe marks the component to be checked for * changes. When the component gets destroyed, the `async` pipe unsubscribes automatically to avoid diff --git a/packages/common/src/pipes/date_pipe.ts b/packages/common/src/pipes/date_pipe.ts index da00c9ca9b1d2..239122eca2fce 100644 --- a/packages/common/src/pipes/date_pipe.ts +++ b/packages/common/src/pipes/date_pipe.ts @@ -13,34 +13,11 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error'; // clang-format off /** * @ngModule CommonModule - * @whatItDoes Uses the function {@link formatDate} to format a date according to locale rules. - * @howToUse `date_expression | date[:format[:timezone[:locale]]]` * @description * - * 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). + * Uses the function {@link formatDate} to format a date according to locale rules. * + * The following tabled describes the formatting options. * * | Field Type | Format | Description | Example Value | * |--------------------|-------------|---------------------------------------------------------------|------------------------------------------------------------| @@ -129,6 +106,31 @@ 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/deprecated/date_pipe.ts b/packages/common/src/pipes/deprecated/date_pipe.ts index 7cbd954cc0695..d098773632684 100644 --- a/packages/common/src/pipes/deprecated/date_pipe.ts +++ b/packages/common/src/pipes/deprecated/date_pipe.ts @@ -13,10 +13,10 @@ import {DateFormatter} from './intl'; /** * @ngModule CommonModule - * @whatItDoes Formats a date according to locale rules. - * @howToUse `date_expression | date[:format]` * @description * + * Formats a date according to locale rules. + * * Where: * - `expression` is a date object or a number (milliseconds since UTC epoch) or an ISO string * (https://www.w3.org/TR/NOTE-datetime). diff --git a/packages/common/src/pipes/deprecated/number_pipe.ts b/packages/common/src/pipes/deprecated/number_pipe.ts index 492501bd38f6f..fb703ea4165fe 100644 --- a/packages/common/src/pipes/deprecated/number_pipe.ts +++ b/packages/common/src/pipes/deprecated/number_pipe.ts @@ -61,8 +61,6 @@ function formatNumber( /** * @ngModule CommonModule - * @whatItDoes Formats a number according to locale rules. - * @howToUse `number_expression | number[:digitInfo]` * * Formats a number as text. Group sizing and separator and other locale-specific * configurations are based on the active locale. @@ -98,12 +96,10 @@ export class DeprecatedDecimalPipe implements PipeTransform { /** * @ngModule CommonModule - * @whatItDoes Formats a number as a percentage according to locale rules. - * @howToUse `number_expression | percent[:digitInfo]` * * @description * - * Formats a number as percentage. + * Formats a number as percentage according to locale rules. * * - `digitInfo` See {@link DecimalPipe} for detailed description. * @@ -128,10 +124,10 @@ export class DeprecatedPercentPipe implements PipeTransform { /** * @ngModule CommonModule - * @whatItDoes Formats a number as currency using locale rules. - * @howToUse `number_expression | currency[:currencyCode[:symbolDisplay[:digitInfo]]]` * @description * + * Formats a number as currency using locale rules. + * * Use `currency` to format a number as currency. * * - `currencyCode` is the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code, such diff --git a/packages/common/src/pipes/i18n_plural_pipe.ts b/packages/common/src/pipes/i18n_plural_pipe.ts index 7f2dd640ad0e0..2ed3eb5138260 100644 --- a/packages/common/src/pipes/i18n_plural_pipe.ts +++ b/packages/common/src/pipes/i18n_plural_pipe.ts @@ -14,16 +14,9 @@ const _INTERPOLATION_REGEXP: RegExp = /#/g; /** * @ngModule CommonModule - * @whatItDoes Maps a value to a string that pluralizes the value according to locale rules. - * @howToUse `expression | i18nPlural:mapping[:locale]` * @description * - * 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) + * Maps a value to a string that pluralizes the value according to locale rules. * * ## Example * @@ -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 84a44e44269a2..0ff8460d011f3 100644 --- a/packages/common/src/pipes/i18n_select_pipe.ts +++ b/packages/common/src/pipes/i18n_select_pipe.ts @@ -11,23 +11,26 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error'; /** * @ngModule CommonModule - * @whatItDoes Generic selector that displays the string that matches the current value. - * @howToUse `expression | i18nSelect:mapping` * @description * - * 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. + * Generic selector that displays the string that matches the current value. * - * ## Example + * 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 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/json_pipe.ts b/packages/common/src/pipes/json_pipe.ts index 887c830786640..f0801164a9eb2 100644 --- a/packages/common/src/pipes/json_pipe.ts +++ b/packages/common/src/pipes/json_pipe.ts @@ -10,8 +10,6 @@ import {Pipe, PipeTransform} from '@angular/core'; /** * @ngModule CommonModule - * @whatItDoes Converts value into JSON string. - * @howToUse `expression | json` * @description * * Converts value into string using `JSON.stringify`. Useful for debugging. diff --git a/packages/common/src/pipes/number_pipe.ts b/packages/common/src/pipes/number_pipe.ts index 824b15f4aab30..2c54e235c19a4 100644 --- a/packages/common/src/pipes/number_pipe.ts +++ b/packages/common/src/pipes/number_pipe.ts @@ -13,23 +13,13 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error'; /** * @ngModule CommonModule - * @whatItDoes Uses the function {@link formatNumber} to format a number according to locale rules. - * @howToUse `number_expression | number[:digitInfo[:locale]]` * @description * + * Uses the function {@link formatNumber} to format a number according to locale rules. + * * 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,18 @@ 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; @@ -56,18 +58,10 @@ export class DecimalPipe implements PipeTransform { /** * @ngModule CommonModule - * @whatItDoes Uses the function {@link formatPercent} to format a number as a percentage according - * to locale rules. - * @howToUse `number_expression | percent[:digitInfo[:locale]]` * @description * - * Formats a number as percentage. - * - * 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). + * Uses the function {@link formatPercent} to format a number as a percentage according + * to locale rules. * * ### Example * @@ -79,6 +73,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; @@ -95,28 +96,10 @@ export class PercentPipe implements PipeTransform { /** * @ngModule CommonModule - * @whatItDoes Uses the functions {@link getCurrencySymbol} and {@link formatCurrency} to format a - * number as currency using locale rules. - * @howToUse `number_expression | currency[:currencyCode[:display[:digitInfo[:locale]]]]` * @description * - * Use `currency` to format a number as currency. - * - * 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). + * Uses the functions {@link getCurrencySymbol} and {@link formatCurrency} to format a + * number as currency using locale rules. * * ### Example * @@ -128,6 +111,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 6466d26b1f1f3..af86424e703a1 100644 --- a/packages/common/src/pipes/slice_pipe.ts +++ b/packages/common/src/pipes/slice_pipe.ts @@ -11,32 +11,19 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error'; /** * @ngModule CommonModule - * @whatItDoes Creates a new List or String containing a subset (slice) of the elements. - * @howToUse `array_or_string_expression | slice:start[:end]` * @description * - * 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,21 @@ 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;