docs(common): migrate `@whatItDoes` tags to the description (#23062)

We get the overview for the doc by splitting off the first
paragraph.

PR Close #23062

packages/common/src/directives/ng_class.ts

@@ -11,8 +11,6 @@ import {Directive, DoCheck, ElementRef, Input, IterableChanges, IterableDiffer,
 /**
  * @ngModule CommonModule
  *
- * @whatItDoes Adds and removes CSS classes on an HTML element.
- *
  * @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,8 +16,6 @@ import {SwitchView} from './ng_switch';
 /**
  * @ngModule CommonModule
  *
- * @whatItDoes Adds / removes DOM sub-trees based on a numeric value. Tailored for pluralization.
- *
  * @usageNotes
  * ```
  * <some-element [ngPlural]="value">
@@ -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,8 +83,10 @@ 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.
  *
  * @usageNotes
  * ```

packages/common/src/directives/ng_style.ts

@@ -11,8 +11,6 @@ import {Directive, DoCheck, ElementRef, Input, KeyValueChanges, KeyValueDiffer,
 /**
  * @ngModule CommonModule
  *
- * @whatItDoes Update an HTML element styles.
- *
  * @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,9 +36,6 @@ export class SwitchView {
 /**
  * @ngModule CommonModule
  *
- * @whatItDoes Adds / removes DOM sub-trees when the nest match expressions matches the switch
- *             expression.
- *
  * @usageNotes
  * ```
  *     <container-element [ngSwitch]="switch_expression">
@@ -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,10 +128,6 @@ 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.
- *
  * @usageNotes
  * ```
  * <container-element [ngSwitch]="switch_expression">
@@ -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,10 +168,6 @@ 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.
- *
  * @usageNotes
  * ```
  * <container-element [ngSwitch]="switch_expression">
@@ -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,8 +11,6 @@ import {Directive, EmbeddedViewRef, Input, OnChanges, SimpleChange, SimpleChange
 /**
  * @ngModule CommonModule
  *
- * @whatItDoes Inserts an embedded view from a prepared `TemplateRef`
- *
  * @usageNotes
  * ```
  * <ng-container *ngTemplateOutlet="templateRefExp; context: contextExp"></ng-container>
@@ -20,6 +18,8 @@ import {Directive, EmbeddedViewRef, Input, OnChanges, SimpleChange, SimpleChange
  *
  * @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,8 +42,10 @@ const _observableStrategy = new ObservableStrategy();
 
 /**
  * @ngModule CommonModule
- * @whatItDoes Unwraps a value from an asynchronous primitive.
  * @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,9 +13,10 @@ 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.
  * @description
  *
+ * 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).

packages/common/src/pipes/deprecated/date_pipe.ts

@@ -13,9 +13,10 @@ import {DateFormatter} from './intl';
 
 /**
  * @ngModule CommonModule
- * @whatItDoes Formats a date according to locale rules.
  * @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).

packages/common/src/pipes/deprecated/number_pipe.ts

@@ -61,7 +61,6 @@ function formatNumber(
 
 /**
  * @ngModule CommonModule
- * @whatItDoes Formats a number according to locale rules.
  *
  * Formats a number as text. Group sizing and separator and other locale-specific
  * configurations are based on the active locale.
@@ -97,11 +96,10 @@ export class DeprecatedDecimalPipe implements PipeTransform {
 
 /**
  * @ngModule CommonModule
- * @whatItDoes Formats a number as a percentage according to locale rules.
  *
  * @description
  *
- * Formats a number as percentage.
+ * Formats a number as percentage according to locale rules.
  *
  * - `digitInfo` See {@link DecimalPipe} for detailed description.
  *
@@ -126,9 +124,10 @@ export class DeprecatedPercentPipe implements PipeTransform {
 
 /**
  * @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.
  *
  * - `currencyCode` is the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code, such

packages/common/src/pipes/i18n_plural_pipe.ts

@@ -14,9 +14,10 @@ const _INTERPOLATION_REGEXP: RegExp = /#/g;
 
 /**
  * @ngModule CommonModule
- * @whatItDoes Maps a value to a string that pluralizes the value according to locale rules.
  * @description
  *
+ * 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

packages/common/src/pipes/i18n_select_pipe.ts

@@ -11,9 +11,10 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
 
 /**
  * @ngModule CommonModule
- * @whatItDoes Generic selector that displays the string that matches the current value.
  * @description
  *
+ * 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

packages/common/src/pipes/json_pipe.ts

@@ -10,7 +10,6 @@ import {Pipe, PipeTransform} from '@angular/core';
 
 /**
  * @ngModule CommonModule
- * @whatItDoes Converts value into JSON string.
  * @description
  *
  * Converts value into string using `JSON.stringify`. Useful for debugging.

packages/common/src/pipes/number_pipe.ts

@@ -13,9 +13,10 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
 
 /**
  * @ngModule CommonModule
- * @whatItDoes Uses the function {@link formatNumber} to format a number according to locale rules.
  * @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.
  *
@@ -55,11 +56,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.
  * @description
  *
- * Formats a number as percentage.
+ * Uses the function {@link formatPercent} to format a number as a percentage according
+ * to locale rules.
  *
  * Where:
  * - `value` is a number.
@@ -93,11 +93,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.
  * @description
  *
- * Use `currency` to format a number as currency.
+ * Uses the functions {@link getCurrencySymbol} and {@link formatCurrency} to format a
+ * number as currency using locale rules.
  *
  * Where:
  * - `value` is a number.

packages/common/src/pipes/slice_pipe.ts

@@ -11,9 +11,10 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
 
 /**
  * @ngModule CommonModule
- * @whatItDoes Creates a new List or String containing a subset (slice) of the elements.
  * @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