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;