docs: incorporate suggestions and corrections from gkalpak (angular#2…

…1569)

PR Close angular#21569

aio/content/guide/architecture-components.md

@@ -2,7 +2,7 @@
 
 <img src="generated/images/guide/architecture/hero-component.png" alt="Component" class="left">
 
-A _component_ controls a patch of screen called a *view*. For example, individual components define and control each of the following views from the Tutorial:
+A _component_ controls a patch of screen called a *view*. For example, individual components define and control each of the following views from the [Tutorial](tutorial/index):
 
 * The app root with the navigation links.
 * The list of heroes.
@@ -50,17 +50,17 @@ in order to get the list of heroes to display.
 
 You define a component's view with its companion template. A template is a form of HTML that tells Angular how to render the component.
 
-Components and their associated views are typically arranged hierarchically, allowing you to modify or show and hide entire UI sections or pages as a unit. The template immediately associated with a component defines that component's _host view_. The template can also define a _view hierarchy_, which can contain _embedded views_, as well as views hosted by other components.
+Views are typically arranged hierarchically, allowing you to modify or show and hide entire UI sections or pages as a unit. The template immediately associated with a component defines that component's _host view_. The component can also define a _view hierarchy_, which contains _embedded views_, hosted by other components.
 
 <figure>
 <img src="generated/images/guide/architecture/component-tree.png" alt="Component tree" class="left">
 </figure>
 
-A view hierarchy can include views from the component's own child components, but it also can (and often does) include views from components that are defined in different NgModules.
+A view hierarchy can include views from components in the same NgModule, but it also can (and often does) include views from components that are defined in different NgModules.
 
 ## Template syntax
 
-A template looks like regular HTML, except that it also contains Angular [template syntax](guide/template-syntax), which alters the HTML before the view is rendered, based on your app's logic and the state of app and DOM data. Your template can use _data binding_ to coordinate the app and DOM data, _pipes_ to transform data before it is displayed, and _directives_ to apply app logic to what gets displayed.
+A template looks like regular HTML, except that it also contains Angular [template syntax](guide/template-syntax), which alters the HTML based on your app's logic and the state of app and DOM data. Your template can use _data binding_ to coordinate the app and DOM data, _pipes_ to transform data before it is displayed, and _directives_ to apply app logic to what gets displayed.
 
 For example, here is a template for the Tutorial's `HeroListComponent`:
 
@@ -70,7 +70,7 @@ This template uses typical HTML elements like `<h2>` and  `<p>`, and also includ
 
 * The  `*ngFor` directive tells Angular to iterate over a list.
 * The `{{hero.name}}`, `(click)`, and `[hero]` bind program data to and from the DOM, responding to user input. See more about [data binding](#data-binding) below.
-* The `<app-hero-detail>` tag in the example is a custom element that represents a new component, `HeroDetailComponent`.  The `HeroDetailComponent`  (code not shown) is a child component of the `HeroListComponent` that defines the Hero-detail view. Notice how custom components like this mix seamlessly with native HTML in the same layouts.
+* The `<app-hero-detail>` tag in the example is an element that represents a new component, `HeroDetailComponent`.  The `HeroDetailComponent`  (code not shown) is a child component of the `HeroListComponent` that defines the Hero-detail view. Notice how custom components like this mix seamlessly with native HTML in the same layouts.
 
 ### Data binding
 
@@ -94,9 +94,9 @@ displays the component's `hero.name` property value within the `<li>` element.
 * The `[hero]` [*property binding*](guide/template-syntax#property-binding) passes the value of `selectedHero` from
 the parent `HeroListComponent` to the `hero` property of the child `HeroDetailComponent`.
 
-* The `(click)` [*event binding*](guide/user-input#click) calls the component's `selectHero` method when the user clicks a hero's name.
+* The `(click)` [*event binding*](guide/user-input#binding-to-user-input-events) calls the component's `selectHero` method when the user clicks a hero's name.
 
-**Two-way data binding** is an important fourth form that combines property and event binding in a single notation, using the `ngModel` directive. Here's an example from the `HeroDetailComponent` template:
+**Two-way data binding** is an important fourth form that combines property and event binding in a single notation. Here's an example from the `HeroDetailComponent` template that uses two-way data binding with the `ngModel` directive:
 
 <code-example path="architecture/src/app/hero-detail.component.html" linenums="false" title="src/app/hero-detail.component.html (ngModel)" region="ngModel"></code-example>
 
@@ -121,13 +121,24 @@ Data binding plays an important role in communication between a template and its
 
  Angular pipes let you declare display-value transformations in your template HTML. A class with the `@Pipe` decorator defines a function that transforms input values to output values for display in a view.
 
- Angular defines various pipes, such as the [Date](https://angular.io/api/common/DatePipe) pipe and [Currency](https://angular.io/api/common/CurrencyPipe) pipe; for a complete list, see the [Pipes API list](https://angular.io/api?type=pipe). You can also define new pipes.
+ Angular defines various pipes, such as the [date](https://angular.io/api/common/DatePipe) pipe and [currency](https://angular.io/api/common/CurrencyPipe) pipe; for a complete list, see the [Pipes API list](https://angular.io/api?type=pipe). You can also define new pipes.
 
  To specify a value transformation in an HTML template, use the [pipe operator (|)](https://angular.io/guide/template-syntax#pipe):
 
  `{{interpolated_value | pipe_name}}`
 
- You can chain pipes, sending the output of one pipe function to be transformed by another pipe function.
+ You can chain pipes, sending the output of one pipe function to be transformed by another pipe function. A pipe can also take arguments that control how it performs its transformation. For example, you can pass the desired format to the `date` pipe:
+
+ ```
+  <!-- Default format: output 'Jun 15, 2015'-->
+  <p>Today is {{today | date}}</p>
+
+ <!-- fullDate format: output 'Monday, June 15, 2015'-->
+ <p>The date is {{today | date:'fullDate'}}</p>
+
+  <!-- shortTime format: output '9:43 AM'-->
+  <p>The time is {{today | date:'shortTime'}}</p>
+```
 
 <hr/>
 

aio/content/guide/architecture-modules.md

@@ -18,7 +18,7 @@ An NgModule is defined as a class decorated with `@NgModule`. The `@NgModule` de
 
 * `imports`—Other modules whose exported classes are needed by component templates declared in _this_ NgModule.
 
-* `providers`—Creators of [services](guide/architecture-services) that this NgModule contributes to the global collection of services; they become accessible in all parts of the app.
+* `providers`—Creators of [services](guide/architecture-services) that this NgModule contributes to the global collection of services; they become accessible in all parts of the app. (You can also specify providers at the component level, which is often preferred.)
 
 * `bootstrap`—The main application view, called the _root component_, which hosts all other app views. Only the _root NgModule_ should set this `bootstrap` property.
 
@@ -28,13 +28,13 @@ Here's a simple root NgModule definition:
 
 <div class="l-sub-section">
 
-  The `export` of `AppComponent` is just to show how to export; it isn't actually necessary in this example. A root NgModule has no reason to _export_ anything because other components don't need to _import_ the root NgModule.
+  The `export` of `AppComponent` is just to show how to export; it isn't actually necessary in this example. A root NgModule has no reason to _export_ anything because other modules don't need to _import_ the root NgModule.
 
 </div>
 
 ## NgModules and components
 
-NgModules provide a _compilation context_ for their components. An NgModule has a root component, created during bootstrap, and any number of additional components that can be loaded (through the router) or created (through the template). The components that belong to an NgModule share a compilation context.
+NgModules provide a _compilation context_ for their components. A root NgModule always has a root component that is created during bootstrap, but any NgModule can include any number of additional components, which can be loaded through the router or created through the template. The components that belong to an NgModule share a compilation context.
 
 <figure>
 

aio/content/guide/architecture-services.md

@@ -20,8 +20,7 @@ Here's an example of a service class that logs to the browser console:
 
 <code-example path="architecture/src/app/logger.service.ts" linenums="false" title="src/app/logger.service.ts (class)" region="class"></code-example>
 
-Here's a `HeroService` that uses a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) to fetch heroes.
-The `HeroService` depends on the `Logger` service and another `BackendService` that handles the server communication grunt work.
+Services can depend on other services. For example, here's a `HeroService` that depends on the `Logger` service, and also uses `BackendService` to get heroes. That service in turn might depend on the `HttpClient` service to fetch heroes asynchronously from a server.
 
 <code-example path="architecture/src/app/hero.service.ts" linenums="false" title="src/app/hero.service.ts (class)" region="class"></code-example>
 
@@ -31,17 +30,21 @@ The `HeroService` depends on the `Logger` service and another `BackendService` t
 
 <img src="generated/images/guide/architecture/dependency-injection.png" alt="Service" class="left">
 
-Components consume services; that is, you can *inject* a service into a component, giving the component access to that service class. To define a class as a service in Angular, use the `@Injectable` decorator to provide the metadata that allows Angular to inject it into a component as a *dependency*. Most dependencies are services.
-
-*Dependency injection* (often called DI) is wired into the Angular framework and used everywhere to provide new components with the services they need.
+Components consume services; that is, you can *inject* a service into a component, giving the component access to that service class. 
+
+To define a class as a service in Angular, use the `@Injectable` decorator to provide the metadata that allows Angular to inject it into a component as a *dependency*.  
+
+Similarly, use the `@Injectable` decorator to indicate that a component or other class (such as another service, a pipe, or an NgModule) _has_ a dependency. A dependency doesn't have to be a service&mdash;it could be a function, for example, or a value. 
+
+*Dependency injection* (often called DI) is wired into the Angular framework and used everywhere to provide new components with the services or other things they need.
 
 * The *injector* is the main mechanism. You don't have to create an Angular injector. Angular creates an application-wide injector for you during the bootstrap process.
 
-* The injector maintains a *container* of service instances that it has already created, and reuses them if possible.
+* The injector maintains a *container* of dependency instances that it has already created, and reuses them if possible.
 
-* A *provider* is a recipe for creating a service -- typically the service class itself. For any service you need in your app, you must register a provider with the app's injector, so that the injector can use it to create new service instances.
+* A *provider* is a recipe for creating a dependency. For a service, this is typically the service class itself. For any dependency you need in your app, you must register a provider with the app's injector, so that the injector can use it to create new instances.
 
-When Angular creates a new instance of a component class, it determines which services that component needs by looking at the types of its constructor parameters. For example, the constructor of `HeroListComponent` needs a `HeroService`:
+When Angular creates a new instance of a component class, it determines which services or other dependencies that component needs by looking at the types of its constructor parameters. For example, the constructor of `HeroListComponent` needs a `HeroService`:
 
 <code-example path="architecture/src/app/hero-list.component.ts" linenums="false" title="src/app/hero-list.component.ts (constructor)" region="ctor"></code-example>