docs(common): migrate deprecated jsdoc tags

aio/tools/transforms/templates/api/lib/paramList.html

@@ -21,11 +21,12 @@
       {% if showType %}<td class="param-type"><code>{$ parameter.type $}</code></td>{% endif %}
       <td class="param-description">
       {% 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 %}<p>Type: <code>{$ parameter.type $}</code>.</p>
-        {% endif %}
+      {% elseif not showType and parameter.type %}<p>Type: <code>{$ parameter.type $}</code>.</p>
+      {% endif %}
+
+      {% if parameter.isOptional or parameter.defaultValue !== undefined %}Optional. Default is `{$ parameter.defaultValue === undefined and 'undefined' or parameter.defaultValue $}`.{% endif %}
       {% endmarked %}
       </td>
     </tr>{% endfor %}

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
  * ```
  *     <some-element [ngClass]="'first second'">...</some-element>
  *
@@ -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,

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
  * ```
  * <some-element [ngPlural]="value">
  *   <ng-template ngPluralCase="=0">there is nothing</ng-template>
@@ -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
  * ```
  * <some-element [ngPlural]="value">
  *   <ng-template ngPluralCase="=0">...</ng-template>

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
  * ```
  * <some-element [ngStyle]="{'font-style': styleExp}">...</some-element>
  *
@@ -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 `.<unit>` suffix (ie 'top.px', 'font-style.em'),
  * - values are the values assigned to those properties (expressed in the given unit).

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
  * ```
  *     <container-element [ngSwitch]="switch_expression">
  *       <some-element *ngSwitchCase="match_expression_1">...</some-element>
@@ -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,18 +128,18 @@ 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
  * ```
  * <container-element [ngSwitch]="switch_expression">
  *   <some-element *ngSwitchCase="match_expression_1">...</some-element>
  * </container-element>
  *```
  * @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
  * ```
  * <container-element [ngSwitch]="switch_expression">
  *   <some-element *ngSwitchCase="match_expression_1">...</some-element>
@@ -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.
  *

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
  * ```
  * <ng-container *ngTemplateOutlet="templateRefExp; context: contextExp"></ng-container>
  * ```
  *
  * @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.

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).

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

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.
  *

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.
  *

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.
  *

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<Promise<any>>('Location Initialized');
 
 /**
- * A serializable version of the event from onPopState or onHashChange
+ * @description
+ * A serializable version of the event from `onPopState` or `onHashChange`
  *
  * @experimental
  */

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

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;
 

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).