From f1d58efdb11ddfe46ecdf10fbca6fff3737eea9e Mon Sep 17 00:00:00 2001 From: Teri Glover Date: Wed, 19 May 2021 20:20:35 +0000 Subject: [PATCH] docs: Edits to remove jargon in Reference Observables, Dependency Injection (#42185) PR Close #42185 --- .../guide/dependency-injection-in-action.md | 4 +- .../hierarchical-dependency-injection.md | 45 +++++++++---------- aio/content/guide/observables.md | 2 +- aio/content/guide/rx-library.md | 6 +-- 4 files changed, 28 insertions(+), 29 deletions(-) diff --git a/aio/content/guide/dependency-injection-in-action.md b/aio/content/guide/dependency-injection-in-action.md index f25c5452b3..fe86e742f7 100644 --- a/aio/content/guide/dependency-injection-in-action.md +++ b/aio/content/guide/dependency-injection-in-action.md @@ -136,7 +136,7 @@ Angular throws an error if the parent lacks that service, even if a component hi in the component tree includes it. A second `@Host()` function decorates the `loggerService` constructor property. -The only `LoggerService` instance in the app is provided at the `AppComponent` level. +The only `LoggerService` instance in the application is provided at the `AppComponent` level. The host `HeroBioComponent` doesn't have its own `LoggerService` provider. Angular throws an error if you haven't also decorated the property with `@Optional()`. @@ -162,7 +162,7 @@ with the "!!!" marker to indicate that the logger was found. If you restore the `@Host()` decorator and comment out `@Optional`, -the app throws an exception when it cannot find the required logger at the host component level. +the application throws an exception when it cannot find the required logger at the host component level. `EXCEPTION: No provider for LoggerService! (HeroContactComponent -> LoggerService)` diff --git a/aio/content/guide/hierarchical-dependency-injection.md b/aio/content/guide/hierarchical-dependency-injection.md index afd470b648..3d33a5a35e 100644 --- a/aio/content/guide/hierarchical-dependency-injection.md +++ b/aio/content/guide/hierarchical-dependency-injection.md @@ -1,7 +1,7 @@ # Hierarchical injectors Injectors in Angular have rules that you can leverage to -achieve the desired visibility of injectables in your apps. +achieve the desired visibility of injectables in your applications. By understanding these rules, you can determine in which NgModule, Component or Directive you should declare a provider. @@ -34,7 +34,7 @@ Using the `@Injectable()` `providedIn` property is preferable to the `@NgModule()` `providers` array because with `@Injectable()` `providedIn`, optimization tools can perform -tree-shaking, which removes services that your app isn't +tree-shaking, which removes services that your application isn't using and results in smaller bundle sizes. Tree-shaking is especially useful for a library @@ -76,7 +76,7 @@ here `root`, which makes the service available in the `root` `ModuleInjector`. There are two more injectors above `root`, an additional `ModuleInjector` and `NullInjector()`. -Consider how Angular bootstraps the app with the +Consider how Angular bootstraps the application with the following in `main.ts`: ```javascript @@ -89,10 +89,10 @@ This is the `root` `ModuleInjector`. The `platformBrowserDynamic()` method creates an injector configured by a `PlatformModule`, which contains platform-specific -dependencies. This allows multiple apps to share a platform +dependencies. This allows multiple applications to share a platform configuration. For example, a browser has only one URL bar, no matter how -many apps you have running. +many applications you have running. You can configure additional platform-specific providers at the platform level by supplying `extraProviders` using the `platformBrowser()` function. @@ -128,7 +128,7 @@ with `root` in their own services. If you configure an app-wide provider in the `@NgModule()` of `AppModule`, it overrides one configured for `root` in the `@Injectable()` metadata. You can do this to configure a -non-default provider of a service that is shared with multiple apps. +non-default provider of a service that is shared with multiple applications. Here is an example of the case where the component router configuration includes @@ -163,7 +163,7 @@ export class TestComponent
-**Note:** Please see the +**Note:** See the [resolution rules](guide/hierarchical-dependency-injection#resolution-rules) section to understand the relationship between the `ModuleInjector` tree and the `ElementInjector` tree. @@ -171,7 +171,7 @@ the `ElementInjector` tree.
-When you provide services in a component, that service is available via +When you provide services in a component, that service is available by way of the `ElementInjector` at that component instance. It may also be visible at child component/directives based on visibility rules described in the [resolution rules](guide/hierarchical-dependency-injection#resolution-rules) section. @@ -227,7 +227,7 @@ Angular's resolution behavior can be modified with `@Optional()`, `@Self()`, `@SkipSelf()` and `@Host()`. Import each of them from `@angular/core` and use each in the component class constructor when you inject your service. -For a working app showcasing the resolution modifiers that +For a working application showcasing the resolution modifiers that this section covers, see the resolution modifiers example. ### Types of modifiers @@ -250,8 +250,7 @@ Additionally, you can combine all of the modifiers except `@Host()` and `@Self() ### `@Optional()` `@Optional()` allows Angular to consider a service you inject to be optional. -This way, if it can't be resolved at runtime, Angular simply -resolves the service as `null`, rather than throwing an error. In +This way, if it can't be resolved at runtime, Angular resolves the service as `null`, rather than throwing an error. In the following example, the service, `OptionalService`, isn't provided in the service, `@NgModule()`, or component class, so it isn't available anywhere in the app. @@ -389,7 +388,7 @@ Understanding the idea of the `<#VIEW>` demarcation is especially significant wh ## Providing services in `@Component()` -How you provide services via an `@Component()` (or `@Directive()`) +How you provide services using a `@Component()` (or `@Directive()`) decorator determines their visibility. The following sections demonstrate `providers` and `viewProviders` along with ways to modify service visibility with `@SkipSelf()` and `@Host()`. @@ -442,14 +441,14 @@ should be used at this location. ### Example app structure -The example app has a `FlowerService` provided in `root` with an `emoji` +The example application has a `FlowerService` provided in `root` with an `emoji` value of `🌺` (red hibiscus). -Consider a simple app with only an `AppComponent` and a `ChildComponent`. +Consider an application with only an `AppComponent` and a `ChildComponent`. The most basic rendered view would look like nested HTML elements such as the following: @@ -480,7 +479,7 @@ Notice that each component has its own `<#VIEW>`. Knowledge of this structure can inform how you provide and inject your services, and give you complete control of service visibility. -Now, consider that `` simply injects the `FlowerService`: +Now, consider that `` injects the `FlowerService`: @@ -535,7 +534,7 @@ In the example case, the constraints are: are special in that they also include their own `viewProviders`, which is why the search starts at `<#VIEW>` belonging to ``. (This would not be the case for a directive matched at the same location). - - The ending location just happens to be the same as the component + - The ending location happens to be the same as the component itself, because it is the topmost component in this application. 2. The `AppModule` acts as the fallback injector when the @@ -615,7 +614,7 @@ set it up on your own, skip ahead to [Modifying service availability](guide/hier -The example app features a second service, the `AnimalService` to +The example application features a second service, the `AnimalService` to demonstrate `viewProviders`. First, create an `AnimalService` with an `emoji` property of 🐳 (whale): @@ -852,7 +851,7 @@ In a logical tree, this same idea might look like this: ``` -Though `` provides the 🌻 (sunflower), the app renders +Though `` provides the 🌻 (sunflower), the application renders the 🌺 (red hibiscus) because `@SkipSelf()` causes the current injector to skip itself and look to its parent. @@ -880,7 +879,7 @@ for `FlowerService`, so it doesn't find it and returns `null`.
-**Note:** The example app uses `@Optional()` so the app does +**Note:** The example application uses `@Optional()` so the application does not throw an error, but the principles are the same.
@@ -892,7 +891,7 @@ the `viewProviders` array with the value of 🐶 (puppy). Because the injector has only to look at the ``'s `ElementInjector` for the `AnimalService`, it never sees the 🐳 (whale). -Just as in the `FlowerService` example, if you add `@SkipSelf()` +As in the `FlowerService` example, if you add `@SkipSelf()` to the constructor for the `AnimalService`, the injector won't look in the current ``'s `ElementInjector` for the `AnimalService`. @@ -1035,7 +1034,7 @@ The logical tree representation shows why this is: the `AnimalService` at the ``, not the ``, where the request originates, and `@Host()` stops the search at the `` `<#VIEW>`. Since `AnimalService` is -provided via the `viewProviders` array, the injector finds 🦔 +provided by way of the `viewProviders` array, the injector finds 🦔 (hedgehog) in the `<#VIEW>`. @@ -1101,7 +1100,7 @@ Each tax return component has the following characteristics: Suppose that the `HeroTaxReturnComponent` had logic to manage and restore changes. -That would be a pretty easy task for a simple hero tax return. +That would be a straightforward task for a hero tax return. In the real world, with a rich tax return data model, the change management would be tricky. You could delegate that management to a helper service, as this example does. @@ -1121,7 +1120,7 @@ Here is the `HeroTaxReturnComponent` that makes use of `HeroTaxReturnService`. -The _tax-return-to-edit_ arrives via the `@Input()` property, which is implemented with getters and setters. +The _tax-return-to-edit_ arrives by way of the `@Input()` property, which is implemented with getters and setters. The setter initializes the component's own instance of the `HeroTaxReturnService` with the incoming return. The getter always returns what that service says is the current state of the hero. The component also asks the service to save and restore this tax return. diff --git a/aio/content/guide/observables.md b/aio/content/guide/observables.md index 425ced5d30..66d5f20c1b 100644 --- a/aio/content/guide/observables.md +++ b/aio/content/guide/observables.md @@ -11,7 +11,7 @@ The subscribed consumer then receives notifications until the function completes An observable can deliver multiple values of any type—literals, messages, or events, depending on the context. The API for receiving values is the same whether the values are delivered synchronously or asynchronously. Because setup and teardown logic are both handled by the observable, your application code only needs to worry about subscribing to consume values, and when done, unsubscribing. Whether the stream was keystrokes, an HTTP response, or an interval timer, the interface for listening to values and stopping listening is the same. -Because of these advantages, observables are used extensively within Angular, and for app development as well. +Because of these advantages, observables are used extensively within Angular, and for application development as well. ## Basic usage and terms diff --git a/aio/content/guide/rx-library.md b/aio/content/guide/rx-library.md index c5462381f8..5b738865e1 100644 --- a/aio/content/guide/rx-library.md +++ b/aio/content/guide/rx-library.md @@ -12,7 +12,7 @@ RxJS provides an implementation of the `Observable` type, which is needed until ## Observable creation functions -RxJS offers a number of functions that can be used to create new observables. These functions can simplify the process of creating observables from things such as events, timers, promises, and so on. For example: +RxJS offers a number of functions that can be used to create new observables. These functions can simplify the process of creating observables from things such as events, timers, and promises. For example: @@ -48,7 +48,7 @@ The `pipe()` function is also a method on the RxJS `Observable`, so you use this RxJS provides many operators, but only a handful are used frequently. For a list of operators and usage samples, visit the [RxJS API Documentation](https://rxjs.dev/api).
- Note that, for Angular apps, we prefer combining operators with pipes, rather than chaining. Chaining is used in many RxJS examples. + Note that, for Angular applications, we prefer combining operators with pipes, rather than chaining. Chaining is used in many RxJS examples.
| Area | Operators | @@ -90,7 +90,7 @@ The following converts the previous example to retry the request before catching Because Angular applications are mostly written in TypeScript, you will typically know when a variable is an observable. Although the Angular framework does not enforce a naming convention for observables, you will often see observables named with a trailing “$” sign. -This can be useful when scanning through code and looking for observable values. Also, if you want a property to store the most recent value from an observable, it can be convenient to simply use the same name with or without the “$”. +This can be useful when scanning through code and looking for observable values. Also, if you want a property to store the most recent value from an observable, it can be convenient to use the same name with or without the “$”. For example: