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.