refactor(docs-infra): convert code-example-s that have only region param to @example-s (#59004)

Replace all <code-example>-s within TS files that contain only a path and a region with JSDoc @example-s.

PR Close #59004

packages/common/src/location/location.ts

@@ -43,8 +43,7 @@ export interface PopStateEvent {
  *
  * ### Example
  *
- * <code-example path='common/location/ts/path_location_component.ts'
- * region='LocationComponent'></code-example>
+ * {@example common/location/ts/path_location_component.ts region='LocationComponent'}
  *
  * @publicApi
  */

packages/common/src/pipes/case_conversion_pipes.ts

@@ -20,7 +20,7 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
  * The following example defines a view that allows the user to enter
  * text, and then uses the pipe to convert the input text to all lower case.
  *
- * <code-example path="common/pipes/ts/lowerupper_pipe.ts" region='LowerUpperPipe'></code-example>
+ * {@example common/pipes/ts/lowerupper_pipe.ts region='LowerUpperPipe'}
  *
  * @ngModule CommonModule
  * @publicApi
@@ -68,7 +68,7 @@ const unicodeWordMatch =
  * @usageNotes
  * The following example shows the result of transforming various strings into title case.
  *
- * <code-example path="common/pipes/ts/titlecase_pipe.ts" region='TitleCasePipe'></code-example>
+ * {@example common/pipes/ts/titlecase_pipe.ts region='TitleCasePipe'}
  *
  * @ngModule CommonModule
  * @publicApi

packages/common/src/pipes/number_pipe.ts

@@ -72,7 +72,7 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';
  * according to various format specifications,
  * where the caller's default locale is `en-US`.
  *
- * <code-example path="common/pipes/ts/number_pipe.ts" region='NumberPipe'></code-example>
+ * {@example common/pipes/ts/number_pipe.ts region='NumberPipe'}
  *
  * @publicApi
  */
@@ -130,7 +130,7 @@ export class DecimalPipe implements PipeTransform {
  * into text strings, according to various format specifications,
  * where the caller's default locale is `en-US`.
  *
- * <code-example path="common/pipes/ts/percent_pipe.ts" region='PercentPipe'></code-example>
+ * {@example common/pipes/ts/percent_pipe.ts region='PercentPipe'}
  *
  * @publicApi
  */
@@ -196,7 +196,7 @@ export class PercentPipe implements PipeTransform {
  * into text strings, according to various format specifications,
  * where the caller's default locale is `en-US`.
  *
- * <code-example path="common/pipes/ts/currency_pipe.ts" region='CurrencyPipe'></code-example>
+ * {@example common/pipes/ts/currency_pipe.ts region='CurrencyPipe'}
  *
  * @publicApi
  */

packages/core/src/change_detection/change_detector_ref.ts

@@ -35,8 +35,7 @@ import {ViewRef} from '../render3/view_ref';
  * (`CheckOnce`, rather than the default `CheckAlways`), then forces a second check
  * after an interval.
  *
- * <code-example path="core/ts/change_detect/change-detection.ts"
- * region="mark-for-check"></code-example>
+ * {@example core/ts/change_detect/change-detection.ts region='mark-for-check'}
  *
  * ### Detach change detector to limit how often check occurs
  *
@@ -46,7 +45,7 @@ import {ViewRef} from '../render3/view_ref';
  * less often than the changes actually occur. To do that, we detach
  * the component's change detector and perform an explicit local check every five seconds.
  *
- * <code-example path="core/ts/change_detect/change-detection.ts" region="detach"></code-example>
+ * {@example core/ts/change_detect/change-detection.ts region='detach'}
  *
  *
  * ### Reattaching a detached component
@@ -56,7 +55,7 @@ import {ViewRef} from '../render3/view_ref';
  * when the `live` property is set to false, and reattaches it when the property
  * becomes true.
  *
- * <code-example path="core/ts/change_detect/change-detection.ts" region="reattach"></code-example>
+ * {@example core/ts/change_detect/change-detection.ts region='reattach'}
  *
  * @publicApi
  */

packages/core/src/di/injectable.ts

@@ -56,7 +56,7 @@ export interface InjectableDecorator {
    * The following example shows how a service class is properly
    *  marked so that a supporting service can be injected upon creation.
    *
-   * <code-example path="core/di/ts/metadata_spec.ts" region="Injectable"></code-example>
+   * {@example core/di/ts/metadata_spec.ts region='Injectable'}
    *
    */
   (): TypeDecorator;

packages/core/src/di/injection_token.ts

@@ -30,8 +30,7 @@ import {ɵɵdefineInjectable} from './interface/defs';
  *
  * </div>
  *
- * <code-example format="typescript" language="typescript" path="injection-token/src/main.ts"
- * region="InjectionToken"></code-example>
+ * {@example injection-token/src/main.ts region='InjectionToken'}
  *
  * When creating an `InjectionToken`, you can optionally specify a factory function which returns
  * (possibly by creating) a default value of the parameterized type `T`. This sets up the

packages/core/src/di/metadata.ts

@@ -28,8 +28,7 @@ export interface InjectDecorator {
    * When `@Inject()` is not present, the injector uses the type annotation of the
    * parameter as the provider.
    *
-   * <code-example path="core/di/ts/metadata_spec.ts" region="InjectWithoutDecorator">
-   * </code-example>
+   * {@example core/di/ts/metadata_spec.ts region='InjectWithoutDecorator'}
    *
    * @see [Dependency Injection Guide](guide/di/dependency-injection
    *
@@ -81,8 +80,7 @@ export interface OptionalDecorator {
    *
    * The following code allows the possibility of a `null` result:
    *
-   * <code-example path="core/di/ts/metadata_spec.ts" region="Optional">
-   * </code-example>
+   * {@example core/di/ts/metadata_spec.ts region='Optional'}
    *
    * @see [Dependency Injection Guide](guide/di/dependency-injection.
    */
@@ -127,8 +125,7 @@ export interface SelfDecorator {
    * by the local injector when instantiating the class itself, but not
    * when instantiating a child.
    *
-   * <code-example path="core/di/ts/metadata_spec.ts" region="Self">
-   * </code-example>
+   * {@example core/di/ts/metadata_spec.ts region='Self'}
    *
    * @see {@link SkipSelf}
    * @see {@link Optional}
@@ -173,8 +170,7 @@ export interface SkipSelfDecorator {
    * In the following example, the dependency can be resolved when
    * instantiating a child, but not when instantiating the class itself.
    *
-   * <code-example path="core/di/ts/metadata_spec.ts" region="SkipSelf">
-   * </code-example>
+   * {@example core/di/ts/metadata_spec.ts region='SkipSelf'}
    *
    * @see [Dependency Injection guide](guide/di/di-in-action#skip).
    * @see {@link Self}
@@ -218,8 +214,7 @@ export interface HostDecorator {
    *
    * The following shows use with the `@Optional` decorator, and allows for a `null` result.
    *
-   * <code-example path="core/di/ts/metadata_spec.ts" region="Host">
-   * </code-example>
+   * {@example core/di/ts/metadata_spec.ts region='Host'}
    *
    * For an extended example, see ["Dependency Injection
    * Guide"](guide/di/di-in-action#optional).

packages/core/src/metadata/directives.ts

@@ -418,7 +418,7 @@ export interface ComponentDecorator {
    * The following example creates a component with two data-bound properties,
    * specified by the `inputs` value.
    *
-   * <code-example path="core/ts/metadata/directives.ts" region="component-input"></code-example>
+   * {@example core/ts/metadata/directives.ts region='component-input'}
    *
    *
    * ### Setting component outputs

packages/examples/BUILD.bazel

@@ -13,6 +13,7 @@ filegroup(
         "//packages/examples/core/di/ts/forward_ref:files_for_docgen",
         "//packages/examples/core/testing/ts:files_for_docgen",
         "//packages/examples/forms:files_for_docgen",
+        "//packages/examples/injection-token:files_for_docgen",
         "//packages/examples/platform-browser:files_for_docgen",
         "//packages/examples/router:files_for_docgen",
         "//packages/examples/router/activated-route:files_for_docgen",

packages/examples/injection-token/BUILD.bazel

@@ -0,0 +1,8 @@
+package(default_visibility = ["//visibility:public"])
+
+filegroup(
+    name = "files_for_docgen",
+    srcs = glob([
+        "**/*.ts",
+    ]),
+)

packages/examples/injection-token/src/main.ts

@@ -0,0 +1,26 @@
+// TODO: Add unit tests for this file.
+/* eslint-disable @angular-eslint/no-output-native */
+// #docregion
+import {Injector, InjectionToken} from '@angular/core';
+
+interface MyInterface {
+  someProperty: string;
+}
+
+// #docregion InjectionToken
+
+const TOKEN = new InjectionToken<MyInterface>('SomeToken');
+
+// Setting up the provider using the same token instance
+const providers = [
+  {provide: TOKEN, useValue: {someProperty: 'exampleValue'}}, // Mock value for MyInterface
+];
+
+// Creating the injector with the provider
+const injector = Injector.create({providers});
+
+// Retrieving the value using the same token instance
+const myInterface = injector.get(TOKEN);
+// myInterface is inferred to be MyInterface.
+
+// #enddocregion InjectionToken

packages/forms/src/form_builder.ts

@@ -325,8 +325,7 @@ export class FormBuilder {
    *
    * The following example returns a control with an initial value in a disabled state.
    *
-   * <code-example path="forms/ts/formBuilder/form_builder_example.ts" region="disabled-control">
-   * </code-example>
+   * {@example forms/ts/formBuilder/form_builder_example.ts region='disabled-control'}
    */
   control<T>(
     formState: T | FormControlState<T>,

packages/upgrade/static/testing/src/create_angular_testing_module.ts

@@ -39,7 +39,7 @@ export class AngularTestingModule {
  * The `Ng2AppModule` is the Angular part of our hybrid application and the `ng1AppModule` is the
  * AngularJS part.
  *
- * <code-example path="upgrade/static/ts/full/module.spec.ts" region="angular-setup"></code-example>
+ * {@example upgrade/static/ts/full/module.spec.ts region='angular-setup'}
  *
  * Once this is done we can get hold of services via the Angular `Injector` as normal.
  * Services that are (or have dependencies on) an upgraded AngularJS service, will be instantiated
@@ -48,7 +48,7 @@ export class AngularTestingModule {
  * In the following code snippet, `HeroesService` is an Angular service that depends upon an
  * AngularJS service, `titleCase`.
  *
- * <code-example path="upgrade/static/ts/full/module.spec.ts" region="angular-spec"></code-example>
+ * {@example upgrade/static/ts/full/module.spec.ts region='angular-spec'}
  *
  * <div class="docs-alert docs-alert-important">
  *

packages/upgrade/static/testing/src/create_angularjs_testing_module.ts

@@ -28,8 +28,7 @@ import {UpgradeAppType} from '../../../src/common/src/util';
  * The AngularJS `ng1AppModule`, which is the AngularJS part of our hybrid application and the
  * `Ng2AppModule`, which is the Angular part.
  *
- * <code-example path="upgrade/static/ts/full/module.spec.ts"
- * region="angularjs-setup"></code-example>
+ * {@example upgrade/static/ts/full/module.spec.ts region='angularjs-setup'}
  *
  * Once this is done we can get hold of services via the AngularJS `$injector` as normal.
  * Services that are (or have dependencies on) a downgraded Angular service, will be instantiated as
@@ -38,8 +37,7 @@ import {UpgradeAppType} from '../../../src/common/src/util';
  * In the following code snippet, `heroesService` is a downgraded Angular service that we are
  * accessing from AngularJS.
  *
- * <code-example path="upgrade/static/ts/full/module.spec.ts"
- * region="angularjs-spec"></code-example>
+ * {@example upgrade/static/ts/full/module.spec.ts region='angularjs-spec'}
  *
  * <div class="docs-alert docs-alert-important">
  *