docs(common): fix content errors (#23667)

PR Close #23667

packages/common/src/directives/ng_component_outlet.ts

@@ -16,6 +16,8 @@ import {ComponentFactoryResolver, ComponentRef, Directive, Injector, Input, NgMo
  * `NgComponentOutlet` requires a component type, if a falsy value is set the view will clear and
  * any existing component will get destroyed.
  *
+ * @usageNotes
+ *
  * ### Fine tune control
  *
  * You can control the component creation process by using the following optional attributes:
@@ -50,7 +52,8 @@ import {ComponentFactoryResolver, ComponentRef, Directive, Injector, Input, NgMo
  *                                   ngModuleFactory: moduleFactory;">
  * </ng-container>
  * ```
- * ## Example
+ *
+ * ### A simple example
  *
  * {@example common/ngComponentOutlet/ts/module.ts region='SimpleExample'}
  *

packages/common/src/directives/ng_for_of.ts

@@ -27,6 +27,8 @@ export class NgForOfContext<T> {
  * for each instantiated template inherits from the outer context with the given loop variable
  * set to the current item from the iterable.
  *
+ * @usageNotes
+ *
  * ### Local Variables
  *
  * `NgForOf` provides several exported values that can be aliased to local variables:

packages/common/src/directives/ng_if.ts

@@ -17,13 +17,16 @@ import {Directive, EmbeddedViewRef, Input, TemplateRef, ViewContainerRef, ɵstri
  *  - `then` template is the inline template of `ngIf` unless bound to a different value.
  *  - `else` template is blank unless it is bound.
  *
- * ## Most common usage
+ *
+ * @usageNotes
+ *
+ * ### Most common usage
  *
  * The most common usage of the `ngIf` directive is to conditionally show the inline template as
  * seen in this example:
  * {@example common/ngIf/ts/module.ts region='NgIfSimple'}
  *
- * ## Showing an alternative template using `else`
+ * ### Showing an alternative template using `else`
  *
  * If it is necessary to display a template when the `expression` is falsy use the `else` template
  * binding as shown. Note that the `else` binding points to a `<ng-template>` labeled `#elseBlock`.
@@ -32,7 +35,7 @@ import {Directive, EmbeddedViewRef, Input, TemplateRef, ViewContainerRef, ɵstri
  *
  * {@example common/ngIf/ts/module.ts region='NgIfElse'}
  *
- * ## Using non-inlined `then` template
+ * ### Using non-inlined `then` template
  *
  * Usually the `then` template is the inlined template of the `ngIf`, but it can be changed using
  * a binding (just like `else`). Because `then` and `else` are bindings, the template references can
@@ -40,7 +43,7 @@ import {Directive, EmbeddedViewRef, Input, TemplateRef, ViewContainerRef, ɵstri
  *
  * {@example common/ngIf/ts/module.ts region='NgIfThenElse'}
  *
- * ## Storing conditional result in a variable
+ * ### Storing conditional result in a variable
  *
  * A common pattern is that we need to show a set of properties from the same object. If the
  * object is undefined, then we have to use the safe-traversal-operator `?.` to guard against

packages/common/src/directives/ng_template_outlet.ts

@@ -11,11 +11,6 @@ import {Directive, EmbeddedViewRef, Input, OnChanges, SimpleChange, SimpleChange
 /**
  * @ngModule CommonModule
  *
- * @usageNotes
- * ```
- * <ng-container *ngTemplateOutlet="templateRefExp; context: contextExp"></ng-container>
- * ```
- *
  * @description
  *
  * Inserts an embedded view from a prepared `TemplateRef`.
@@ -24,13 +19,17 @@ import {Directive, EmbeddedViewRef, Input, OnChanges, SimpleChange, SimpleChange
  * `[ngTemplateOutletContext]` should be an object, the object's keys will be available for binding
  * by the local template `let` declarations.
  *
- * Note: using the key `$implicit` in the context object will set its value as default.
+ * @usageNotes
+ * ```
+ * <ng-container *ngTemplateOutlet="templateRefExp; context: contextExp"></ng-container>
+ * ```
  *
- * ## Example
+ * Using the key `$implicit` in the context object will set its value as default.
+ *
+ * ### Example
  *
  * {@example common/ngTemplateOutlet/ts/module.ts region='NgTemplateOutlet'}
  *
- *
  */
 @Directive({selector: '[ngTemplateOutlet]'})
 export class NgTemplateOutlet implements OnChanges {

packages/common/src/location/hash_location_strategy.ts

@@ -25,6 +25,8 @@ import {LocationChangeListener, PlatformLocation} from './platform_location';
  * For instance, if you call `location.go('/foo')`, the browser's URL will become
  * `example.com#/foo`.
  *
+ * @usageNotes
+ *
  * ### Example
  *
  * {@example common/location/ts/hash_location_component.ts region='LocationComponent'}

packages/common/src/location/location.ts

@@ -27,7 +27,9 @@ export interface PopStateEvent {
  * Depending on which {@link LocationStrategy} is used, `Location` will either persist
  * to the URL's path or the URL's hash segment.
  *
- * Note: it's better to use {@link Router#navigate} service to trigger route changes. Use
+ * @usageNotes
+ *
+ * It's better to use {@link Router#navigate} service to trigger route changes. Use
  * `Location` only if you need to interact with or create normalized URLs outside of
  * routing.
  *
@@ -39,6 +41,7 @@ export interface PopStateEvent {
  * - `/my/app/user/123/` **is not** normalized
  *
  * ### Example
+ *
  * {@example common/location/ts/path_location_component.ts region='LocationComponent'}
  *
  */

packages/common/src/location/location_strategy.ts

@@ -47,6 +47,8 @@ export abstract class LocationStrategy {
  * representing the URL prefix that should be preserved when generating and recognizing
  * URLs.
  *
+ * @usageNotes
+ *
  * ### Example
  *
  * ```typescript

packages/common/src/location/path_location_strategy.ts

@@ -34,6 +34,8 @@ import {LocationChangeListener, PlatformLocation} from './platform_location';
  * `location.go('/foo')`, the browser's URL will become
  * `example.com/my/app/foo`.
  *
+ * @usageNotes
+ *
  * ### Example
  *
  * {@example common/location/ts/path_location_component.ts region='LocationComponent'}

packages/common/src/pipes/async_pipe.ts

@@ -51,8 +51,9 @@ const _observableStrategy = new ObservableStrategy();
  * changes. When the component gets destroyed, the `async` pipe unsubscribes automatically to avoid
  * potential memory leaks.
  *
+ * @usageNotes
  *
- * ## Examples
+ * ### Examples
  *
  * This example binds a `Promise` to the view. Clicking the `Resolve` button resolves the
  * promise.
@@ -64,7 +65,6 @@ const _observableStrategy = new ObservableStrategy();
  *
  * {@example common/pipes/ts/async_pipe.ts region='AsyncPipeObservable'}
  *
- *
  */
 @Pipe({name: 'async', pure: false})
 export class AsyncPipe implements OnDestroy, PipeTransform {

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

@@ -64,6 +64,8 @@ import {DateFormatter} from './intl';
  * - this pipe uses the Internationalization API. Therefore it is only reliable in Chrome and Opera
  *   browsers.
  *
+ * @usageNotes
+ *
  * ### Examples
  *
  * Assuming `dateObj` is (year: 2010, month: 9, day: 3, hour: 12 PM, minute: 05, second: 08)

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

@@ -78,11 +78,12 @@ function formatNumber(
  * WARNING: this pipe uses the Internationalization API which is not yet available in all browsers
  * and may require a polyfill. See [Browser Support](guide/browser-support) for details.
  *
+ * @usageNotes
+ *
  * ### Example
  *
  * {@example common/pipes/ts/number_pipe.ts region='DeprecatedNumberPipe'}
  *
- *
  */
 @Pipe({name: 'number'})
 export class DeprecatedDecimalPipe implements PipeTransform {
@@ -106,6 +107,8 @@ export class DeprecatedDecimalPipe implements PipeTransform {
  * WARNING: this pipe uses the Internationalization API which is not yet available in all browsers
  * and may require a polyfill. See [Browser Support](guide/browser-support) for details.
  *
+ * @usageNotes
+ *
  * ### Example
  *
  * {@example common/pipes/ts/percent_pipe.ts region='DeprecatedPercentPipe'}
@@ -140,6 +143,8 @@ export class DeprecatedPercentPipe implements PipeTransform {
  * WARNING: this pipe uses the Internationalization API which is not yet available in all browsers
  * and may require a polyfill. See [Browser Support](guide/browser-support) for details.
  *
+ * @usageNotes
+ *
  * ### Example
  *
  * {@example common/pipes/ts/currency_pipe.ts region='DeprecatedCurrencyPipe'}

packages/common/src/pipes/i18n_plural_pipe.ts

@@ -18,7 +18,9 @@ const _INTERPOLATION_REGEXP: RegExp = /#/g;
  *
  * Maps a value to a string that pluralizes the value according to locale rules.
  *
- *  ## Example
+ * @usageNotes
+ *
+ * ### Example
  *
  * {@example common/pipes/ts/i18n_pipe.ts region='I18nPluralPipeComponent'}
  *

packages/common/src/pipes/i18n_select_pipe.ts

@@ -18,7 +18,9 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
  * 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
+ * @usageNotes
+ *
+ * ### Example
  *
  * {@example common/pipes/ts/i18n_pipe.ts region='I18nSelectPipeComponent'}
  *

packages/common/src/pipes/json_pipe.ts

@@ -18,9 +18,8 @@ import {Pipe, PipeTransform} from '@angular/core';
  *
  * The following component uses a JSON pipe to convert an object
  * to JSON format, and displays the string in both formats for comparison.
-
- * {@example common/pipes/ts/json_pipe.ts region='JsonPipe'}
  *
+ * {@example common/pipes/ts/json_pipe.ts region='JsonPipe'}
  *
  */
 @Pipe({name: 'json', pure: false})

packages/common/src/pipes/number_pipe.ts

@@ -19,20 +19,20 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
  * formatted according to locale rules that determine group sizing and
  * separator, decimal-point character, and other locale-specific
  * configurations.
- * 
+ *
  * If no parameters are specified, the function rounds off to the nearest value using this
  * [rounding method](https://en.wikibooks.org/wiki/Arithmetic/Rounding).
  * The behavior differs from that of the JavaScript ```Math.round()``` function.
- * In the following case for example, the pipe rounds down where 
+ * In the following case for example, the pipe rounds down where
  * ```Math.round()``` rounds up:
- * 
+ *
  * ```html
  * -2.5 | number:'1.0-0'
  * > -3
  * Math.round(-2.5)
  * > -2
  * ```
- * 
+ *
  * @see `formatNumber()`
  *
  * @usageNotes
@@ -44,7 +44,6 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
  *
  * <code-example path="common/pipes/ts/number_pipe.ts" region='NumberPipe'></code-example>
  *
- *
  */
 @Pipe({name: 'number'})
 export class DecimalPipe implements PipeTransform {

packages/common/src/pipes/slice_pipe.ts

@@ -15,6 +15,8 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
  *
  * Creates a new `Array` or `String` containing a subset (slice) of the elements.
  *
+ * @usageNotes
+ *
  * All behavior is based on the expected behavior of the JavaScript API `Array.prototype.slice()`
  * and `String.prototype.slice()`.
  *
@@ -31,14 +33,15 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
  *
  * produces the following:
  *
- *     <li>b</li>
- *     <li>c</li>
+ * ```html
+ * <li>b</li>
+ * <li>c</li>
+ * ```
  *
- * ## String Examples
+ * ### String Examples
  *
  * {@example common/pipes/ts/slice_pipe.ts region='SlicePipe_string'}
  *
- *
  */
 
 @Pipe({name: 'slice', pure: false})