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

hawkgs · pkozlowski-opensource · commit 0c40bb28e1ec · 2024-12-04T18:06:00.000+01:00
Replace all <code-example>-s within TS files that contain only a path and a region with JSDoc @example-s. PR Close #59004
diff --git a/packages/common/src/location/location.ts b/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
  */
diff --git a/packages/common/src/pipes/case_conversion_pipes.ts b/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
diff --git a/packages/common/src/pipes/number_pipe.ts b/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
  */
diff --git a/packages/core/src/change_detection/change_detector_ref.ts b/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
  */
diff --git a/packages/core/src/di/injectable.ts b/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;
diff --git a/packages/core/src/di/injection_token.ts b/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
diff --git a/packages/core/src/di/metadata.ts b/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).
diff --git a/packages/core/src/metadata/directives.ts b/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
diff --git a/packages/examples/BUILD.bazel b/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",
diff --git a/packages/examples/injection-token/BUILD.bazel b/packages/examples/injection-token/BUILD.bazel
@@ -0,0 +1,8 @@
+package(default_visibility = ["//visibility:public"])
+
+filegroup(
+    name = "files_for_docgen",
+    srcs = glob([
+        "**/*.ts",
+    ]),
+)
diff --git a/packages/examples/injection-token/src/main.ts b/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
diff --git a/packages/forms/src/form_builder.ts b/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>,
diff --git a/packages/upgrade/static/testing/src/create_angular_testing_module.ts b/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">
  *
diff --git a/packages/upgrade/static/testing/src/create_angularjs_testing_module.ts b/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">
  *

Original file line number	Diff line number	Diff line change
`@@ -43,8 +43,7 @@ export interface PopStateEvent {`
`43`	`43`	`*`
`44`	`44`	`* ### Example`
`45`	`45`	`*`
`46`		`- * <code-example path='common/location/ts/path_location_component.ts'`
`47`		`- * region='LocationComponent'></code-example>`
	`46`	`+ * {@example common/location/ts/path_location_component.ts region='LocationComponent'}`
`48`	`47`	`*`
`49`	`48`	`* @publicApi`
`50`	`49`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -20,7 +20,7 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';`
`20`	`20`	`* The following example defines a view that allows the user to enter`
`21`	`21`	`* text, and then uses the pipe to convert the input text to all lower case.`
`22`	`22`	`*`
`23`		`- * <code-example path="common/pipes/ts/lowerupper_pipe.ts" region='LowerUpperPipe'></code-example>`
	`23`	`+ * {@example common/pipes/ts/lowerupper_pipe.ts region='LowerUpperPipe'}`
`24`	`24`	`*`
`25`	`25`	`* @ngModule CommonModule`
`26`	`26`	`* @publicApi`
`@@ -68,7 +68,7 @@ const unicodeWordMatch =`
`68`	`68`	`* @usageNotes`
`69`	`69`	`* The following example shows the result of transforming various strings into title case.`
`70`	`70`	`*`
`71`		`- * <code-example path="common/pipes/ts/titlecase_pipe.ts" region='TitleCasePipe'></code-example>`
	`71`	`+ * {@example common/pipes/ts/titlecase_pipe.ts region='TitleCasePipe'}`
`72`	`72`	`*`
`73`	`73`	`* @ngModule CommonModule`
`74`	`74`	`* @publicApi`
Original file line number	Diff line number	Diff line change
`@@ -72,7 +72,7 @@ import {invalidPipeArgumentError} from './invalid_pipe_argument_error';`
`72`	`72`	`* according to various format specifications,`
`73`	`73`	* where the caller's default locale is `en-US`.
`74`	`74`	`*`
`75`		`- * <code-example path="common/pipes/ts/number_pipe.ts" region='NumberPipe'></code-example>`
	`75`	`+ * {@example common/pipes/ts/number_pipe.ts region='NumberPipe'}`
`76`	`76`	`*`
`77`	`77`	`* @publicApi`
`78`	`78`	`*/`
`@@ -130,7 +130,7 @@ export class DecimalPipe implements PipeTransform {`
`130`	`130`	`* into text strings, according to various format specifications,`
`131`	`131`	* where the caller's default locale is `en-US`.
`132`	`132`	`*`
`133`		`- * <code-example path="common/pipes/ts/percent_pipe.ts" region='PercentPipe'></code-example>`
	`133`	`+ * {@example common/pipes/ts/percent_pipe.ts region='PercentPipe'}`
`134`	`134`	`*`
`135`	`135`	`* @publicApi`
`136`	`136`	`*/`
`@@ -196,7 +196,7 @@ export class PercentPipe implements PipeTransform {`
`196`	`196`	`* into text strings, according to various format specifications,`
`197`	`197`	* where the caller's default locale is `en-US`.
`198`	`198`	`*`
`199`		`- * <code-example path="common/pipes/ts/currency_pipe.ts" region='CurrencyPipe'></code-example>`
	`199`	`+ * {@example common/pipes/ts/currency_pipe.ts region='CurrencyPipe'}`
`200`	`200`	`*`
`201`	`201`	`* @publicApi`
`202`	`202`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -35,8 +35,7 @@ import {ViewRef} from '../render3/view_ref';`
`35`	`35`	* (`CheckOnce`, rather than the default `CheckAlways`), then forces a second check
`36`	`36`	`* after an interval.`
`37`	`37`	`*`
`38`		`- * <code-example path="core/ts/change_detect/change-detection.ts"`
`39`		`- * region="mark-for-check"></code-example>`
	`38`	`+ * {@example core/ts/change_detect/change-detection.ts region='mark-for-check'}`
`40`	`39`	`*`
`41`	`40`	`* ### Detach change detector to limit how often check occurs`
`42`	`41`	`*`
`@@ -46,7 +45,7 @@ import {ViewRef} from '../render3/view_ref';`
`46`	`45`	`* less often than the changes actually occur. To do that, we detach`
`47`	`46`	`* the component's change detector and perform an explicit local check every five seconds.`
`48`	`47`	`*`
`49`		`- * <code-example path="core/ts/change_detect/change-detection.ts" region="detach"></code-example>`
	`48`	`+ * {@example core/ts/change_detect/change-detection.ts region='detach'}`
`50`	`49`	`*`
`51`	`50`	`*`
`52`	`51`	`* ### Reattaching a detached component`
`@@ -56,7 +55,7 @@ import {ViewRef} from '../render3/view_ref';`
`56`	`55`	* when the `live` property is set to false, and reattaches it when the property
`57`	`56`	`* becomes true.`
`58`	`57`	`*`
`59`		`- * <code-example path="core/ts/change_detect/change-detection.ts" region="reattach"></code-example>`
	`58`	`+ * {@example core/ts/change_detect/change-detection.ts region='reattach'}`
`60`	`59`	`*`
`61`	`60`	`* @publicApi`
`62`	`61`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -56,7 +56,7 @@ export interface InjectableDecorator {`
`56`	`56`	`* The following example shows how a service class is properly`
`57`	`57`	`* marked so that a supporting service can be injected upon creation.`
`58`	`58`	`*`
`59`		`- * <code-example path="core/di/ts/metadata_spec.ts" region="Injectable"></code-example>`
	`59`	`+ * {@example core/di/ts/metadata_spec.ts region='Injectable'}`
`60`	`60`	`*`
`61`	`61`	`*/`
`62`	`62`	`(): TypeDecorator;`
Original file line number	Diff line number	Diff line change
`@@ -30,8 +30,7 @@ import {ɵɵdefineInjectable} from './interface/defs';`
`30`	`30`	`*`
`31`	`31`	`* </div>`
`32`	`32`	`*`
`33`		`- * <code-example format="typescript" language="typescript" path="injection-token/src/main.ts"`
`34`		`- * region="InjectionToken"></code-example>`
	`33`	`+ * {@example injection-token/src/main.ts region='InjectionToken'}`
`35`	`34`	`*`
`36`	`35`	* When creating an `InjectionToken`, you can optionally specify a factory function which returns
`37`	`36`	* (possibly by creating) a default value of the parameterized type `T`. This sets up the
Original file line number	Diff line number	Diff line change
`@@ -28,8 +28,7 @@ export interface InjectDecorator {`
`28`	`28`	* When `@Inject()` is not present, the injector uses the type annotation of the
`29`	`29`	`* parameter as the provider.`
`30`	`30`	`*`
`31`		`- * <code-example path="core/di/ts/metadata_spec.ts" region="InjectWithoutDecorator">`
`32`		`- * </code-example>`
	`31`	`+ * {@example core/di/ts/metadata_spec.ts region='InjectWithoutDecorator'}`
`33`	`32`	`*`
`34`	`33`	`* @see [Dependency Injection Guide](guide/di/dependency-injection`
`35`	`34`	`*`
`@@ -81,8 +80,7 @@ export interface OptionalDecorator {`
`81`	`80`	`*`
`82`	`81`	* The following code allows the possibility of a `null` result:
`83`	`82`	`*`
`84`		`- * <code-example path="core/di/ts/metadata_spec.ts" region="Optional">`
`85`		`- * </code-example>`
	`83`	`+ * {@example core/di/ts/metadata_spec.ts region='Optional'}`
`86`	`84`	`*`
`87`	`85`	`* @see [Dependency Injection Guide](guide/di/dependency-injection.`
`88`	`86`	`*/`
`@@ -127,8 +125,7 @@ export interface SelfDecorator {`
`127`	`125`	`* by the local injector when instantiating the class itself, but not`
`128`	`126`	`* when instantiating a child.`
`129`	`127`	`*`
`130`		`- * <code-example path="core/di/ts/metadata_spec.ts" region="Self">`
`131`		`- * </code-example>`
	`128`	`+ * {@example core/di/ts/metadata_spec.ts region='Self'}`
`132`	`129`	`*`
`133`	`130`	`* @see {@link SkipSelf}`
`134`	`131`	`* @see {@link Optional}`
`@@ -173,8 +170,7 @@ export interface SkipSelfDecorator {`
`173`	`170`	`* In the following example, the dependency can be resolved when`
`174`	`171`	`* instantiating a child, but not when instantiating the class itself.`
`175`	`172`	`*`
`176`		`- * <code-example path="core/di/ts/metadata_spec.ts" region="SkipSelf">`
`177`		`- * </code-example>`
	`173`	`+ * {@example core/di/ts/metadata_spec.ts region='SkipSelf'}`
`178`	`174`	`*`
`179`	`175`	`* @see [Dependency Injection guide](guide/di/di-in-action#skip).`
`180`	`176`	`* @see {@link Self}`
`@@ -218,8 +214,7 @@ export interface HostDecorator {`
`218`	`214`	`*`
`219`	`215`	* The following shows use with the `@Optional` decorator, and allows for a `null` result.
`220`	`216`	`*`
`221`		`- * <code-example path="core/di/ts/metadata_spec.ts" region="Host">`
`222`		`- * </code-example>`
	`217`	`+ * {@example core/di/ts/metadata_spec.ts region='Host'}`
`223`	`218`	`*`
`224`	`219`	`* For an extended example, see ["Dependency Injection`
`225`	`220`	`* Guide"](guide/di/di-in-action#optional).`
Original file line number	Diff line number	Diff line change
`@@ -418,7 +418,7 @@ export interface ComponentDecorator {`
`418`	`418`	`* The following example creates a component with two data-bound properties,`
`419`	`419`	* specified by the `inputs` value.
`420`	`420`	`*`
`421`		`- * <code-example path="core/ts/metadata/directives.ts" region="component-input"></code-example>`
	`421`	`+ * {@example core/ts/metadata/directives.ts region='component-input'}`
`422`	`422`	`*`
`423`	`423`	`*`
`424`	`424`	`* ### Setting component outputs`