diff --git a/packages/common/src/location/location.ts b/packages/common/src/location/location.ts index 5f4b3c9616d..b7abff148da 100644 --- a/packages/common/src/location/location.ts +++ b/packages/common/src/location/location.ts @@ -43,8 +43,7 @@ export interface PopStateEvent { * * ### 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 index 37e00daf5f9..26a6a1caa47 100644 --- 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. * - * + * {@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. * - * + * {@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 index 31e1b918921..a4bba3b6070 100644 --- 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`. * - * + * {@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`. * - * + * {@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`. * - * + * {@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 index fbab136554d..16bc38c3220 100644 --- 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. * - * + * {@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. * - * + * {@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. * - * + * {@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 index c6ac4dc5d5a..e002f2e6241 100644 --- 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. * - * + * {@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 index 24146ae5053..8b2fd8efecf 100644 --- 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'; * * * - * + * {@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 index 348ef8c2451..40cd31e2e57 100644 --- 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. * - * - * + * {@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: * - * - * + * {@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. * - * - * + * {@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. * - * - * + * {@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. * - * - * + * {@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 index 3f4b9c884fe..3b77ffbc085 100644 --- 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. * - * + * {@example core/ts/metadata/directives.ts region='component-input'} * * * ### Setting component outputs diff --git a/packages/examples/BUILD.bazel b/packages/examples/BUILD.bazel index e6073bad58e..431b64beea5 100644 --- 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 new file mode 100644 index 00000000000..b4b10cd1d18 --- /dev/null +++ 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 new file mode 100644 index 00000000000..8923a32feb9 --- /dev/null +++ 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('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 index e71c8427bc4..7a1fbfff2d0 100644 --- 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. * - * - * + * {@example forms/ts/formBuilder/form_builder_example.ts region='disabled-control'} */ control( formState: T | FormControlState, diff --git a/packages/upgrade/static/testing/src/create_angular_testing_module.ts b/packages/upgrade/static/testing/src/create_angular_testing_module.ts index 3bd01e8d2f2..5489b398d2c 100644 --- 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. * - * + * {@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`. * - * + * {@example upgrade/static/ts/full/module.spec.ts region='angular-spec'} * *
* diff --git a/packages/upgrade/static/testing/src/create_angularjs_testing_module.ts b/packages/upgrade/static/testing/src/create_angularjs_testing_module.ts index dfbcbaf6c1c..48e1a098cdb 100644 --- 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. * - * + * {@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. * - * + * {@example upgrade/static/ts/full/module.spec.ts region='angularjs-spec'} * *
*