diff --git a/aio/content/guide/cheatsheet.md b/aio/content/guide/cheatsheet.md index f184dbe8be..d057555cb2 100644 --- a/aio/content/guide/cheatsheet.md +++ b/aio/content/guide/cheatsheet.md @@ -11,7 +11,7 @@ platformBrowserDynamic().bootstrapModule(AppModule); -

Bootstraps the app, using the root component from the specified NgModule.

+

Bootstraps the application, using the root component from the specified NgModule.

@@ -110,7 +110,7 @@ is available to declarations of this module.

<p>Card No.: {{cardNumber | myCardNumberFormatter}}</p> -

Transforms the current value of expression cardNumber via the pipe called myCardNumberFormatter.

+

Transforms the current value of expression cardNumber using the pipe called myCardNumberFormatter.

<p>Employer: {{employer?.companyName}}</p> @@ -276,7 +276,7 @@ so the @Directive configuration applies to components as well

@Input() myProperty; -

Declares an input property that you can update via property binding (example: +

Declares an input property that you can update using property binding (example: <my-cmp [myProperty]="someExpression">).

diff --git a/aio/content/guide/docs-style-guide.md b/aio/content/guide/docs-style-guide.md index 424a1b6106..ea683fc6a7 100644 --- a/aio/content/guide/docs-style-guide.md +++ b/aio/content/guide/docs-style-guide.md @@ -207,11 +207,11 @@ Do not create a node that is both a header and an item node by specifying the `u ## Code snippets -[Angular.io](https://angular.io/docs) has a custom framework that enables authors to include code snippets directly from working example apps that are automatically tested as part of documentation builds. +[Angular.io](https://angular.io/docs) has a custom framework that enables authors to include code snippets directly from working example applications that are automatically tested as part of documentation builds. In addition to working code snippets, example code can include terminal commands, a fragment of TypeScript or HTML, or an entire code file. -Whatever the source, the doc viewer renders them as code snippets, either individually with the [code-example](#code-example "code-example") component or as a tabbed collection with the [code-tabs](#code-tabs "code-tabs") component. +Whatever the source, the document viewer renders them as code snippets, either individually with the [code-example](#code-example "code-example") component or as a tabbed collection with the [code-tabs](#code-tabs "code-tabs") component. {@a code-example} @@ -278,9 +278,9 @@ For hypothetical examples such as illustrations of configuration options in a JS One of the Angular documentation design goals is that guide page code snippets be examples of working code. -Authors meet this goal by displaying code snippets directly from working sample apps, written specifically for these guide pages. +Authors meet this goal by displaying code snippets directly from working sample applications, written specifically for these guide pages. -Find sample apps in sub-folders of the `content/examples` directory of the `angular/angular` repository. +Find sample applications in sub-folders of the `content/examples` directory of the `angular/angular` repository. An example folder name is often the same as the guide page it supports.
@@ -312,11 +312,11 @@ The following markup produces that snippet: ``` -The `path` attribute identifies the snippet's source file at the example app folder's location within `content/examples`. +The `path` attribute identifies the snippet's source file at the example application folder's location within `content/examples`. In this example, that path is `docs-style-guide/src/app/app.module.ts`. The header tells the reader where to find the file. -Following convention, set the `header` attribute to the file's location within the example app's root folder. +Following convention, set the `header` attribute to the file's location within the example application's root folder. Unless otherwise noted, all code snippets in this page are from sample source code located in the `content/examples/docs-style-guide` directory. @@ -385,7 +385,7 @@ export class AppModule { } The opening and ending `#docregion` lines designate any lines of code between them as being included in the code snippet. This is why the import statements outside of the `class` `#docregion` are not in the code snippet. -For more information on how to prepare example app files for use in guides, see +For more information on how to prepare example application files for use in guides, see [Source code markup](#source-code-markup). ### Code snippet options @@ -903,7 +903,7 @@ The browser renders the following: This is a [link to that custom anchor name](#section-anchors). When editing a file, don't remove any anchors. -If you change the document structure, you can move an existing anchor within that same doc without breaking a link. +If you change the document structure, you can move an existing anchor within that same document without breaking a link. You can also add more anchors with more appropriate text.
diff --git a/aio/content/guide/glossary.md b/aio/content/guide/glossary.md index 19ed0bfb3a..b767eb7057 100644 --- a/aio/content/guide/glossary.md +++ b/aio/content/guide/glossary.md @@ -44,7 +44,7 @@ A structure that provides metadata for a class. See [decorator](#decorator). ## app-shell -App shell is a way to render a portion of your application via a route at build time. +App shell is a way to render a portion of your application using a route at build time. This gives users a meaningful first paint of your application that appears quickly because the browser can render static HTML and CSS without the need to initialize JavaScript. Learn more in [The App Shell Model](https://developers.google.com/web/fundamentals/architecture/app-shell). @@ -99,11 +99,11 @@ between a [token](#token) and a dependency [provider](#provider). ## bootstrap -A way to initialize and launch an app or system. +A way to initialize and launch an application or system. -In Angular, an app's root NgModule (`AppModule`) has a `bootstrap` property that identifies the app's top-level [components](#component). +In Angular, an application's root NgModule (`AppModule`) has a `bootstrap` property that identifies the application's top-level [components](#component). During the bootstrap process, Angular creates and inserts these components into the `index.html` host web page. -You can bootstrap multiple apps in the same `index.html`. Each app contains its own components. +You can bootstrap multiple applications in the same `index.html`. Each application contains its own components. Learn more in [Bootstrapping](guide/bootstrapping). @@ -231,7 +231,7 @@ A web platform feature, currently supported by most browsers and available in ot The custom element feature extends HTML by allowing you to define a tag whose content is created and controlled by JavaScript code. A custom element (also called a *web component*) is recognized by a browser when it's added to the [CustomElementRegistry](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry). -You can use the API to transform an Angular component so that it can be registered with the browser and used in any HTML that you add directly to the DOM within an Angular app. The custom element tag inserts the component's view, with change-detection and data-binding functionality, into content that would otherwise be displayed without Angular processing. +You can use the API to transform an Angular component so that it can be registered with the browser and used in any HTML that you add directly to the DOM within an Angular application. The custom element tag inserts the component's view, with change-detection and data-binding functionality, into content that would otherwise be displayed without Angular processing. See [Angular element](#angular-element). @@ -244,7 +244,7 @@ See also [dynamic component loading](#dynamic-components). ## data binding -A process that allows apps to display data values to a user and respond to user +A process that allows applications to display data values to a user and respond to user actions (such as clicks, touches, and keystrokes). In data binding, you declare the relationship between an HTML widget and a data source @@ -301,7 +301,7 @@ See [class decorator](#class-decorator), [class field decorator](#class-field-de A design pattern and mechanism for creating and delivering some parts of an application (dependencies) to other parts of an application that require them. In Angular, dependencies are typically services, but they also can be values, such as strings or functions. -An [injector](#injector) for an app (created automatically during bootstrap) instantiates dependencies when needed, using a configured [provider](#provider) of the service or value. +An [injector](#injector) for an application (created automatically during bootstrap) instantiates dependencies when needed, using a configured [provider](#provider) of the service or value. Learn more in [Dependency Injection in Angular](guide/dependency-injection). @@ -338,7 +338,7 @@ There are three categories of directive: Angular supplies a number of built-in directives that begin with the `ng` prefix. You can also create new directives to implement your own functionality. -You associate a *selector* (an HTML tag such as ``) with a custom directive, thereby extending the [template syntax](guide/template-syntax) that you can use in your apps. +You associate a *selector* (an HTML tag such as ``) with a custom directive; this extends the [template syntax](guide/template-syntax) that you can use in your applications. **UpperCamelCase**, such as `NgIf`, refers to a directive class. You can use **UpperCamelCase** when describing properties and directive behavior. @@ -351,7 +351,7 @@ You can use **lowerCamelCase** when describing how to apply the directive to an ## domain-specific language (DSL) A special-purpose library or API; see [Domain-specific language](https://en.wikipedia.org/wiki/Domain-specific_language). -Angular extends TypeScript with domain-specific languages for a number of domains relevant to Angular apps, defined in NgModules such as [animations](guide/animations), [forms](guide/forms), and [routing and navigation](guide/router). +Angular extends TypeScript with domain-specific languages for a number of domains relevant to Angular applications, defined in NgModules such as [animations](guide/animations), [forms](guide/forms), and [routing and navigation](guide/router). {@a dynamic-components} @@ -547,15 +547,15 @@ A process that speeds up application load time by splitting the application into For example, dependencies can be lazy loaded as needed—as opposed to [eager-loaded](#eager-loading) modules that are required by the root module and are thus loaded on launch. The [router](#router) makes use of lazy loading to load child views only when the parent view is activated. -Similarly, you can build custom elements that can be loaded into an Angular app when needed. +Similarly, you can build custom elements that can be loaded into an Angular application when needed. {@a library} ## library -In Angular, a [project](#project) that provides functionality that can be included in other Angular apps. -A library isn't a complete Angular app and can't run independently. -(To add re-usable Angular functionality to non-Angular web apps, you can use Angular [custom elements](#angular-element).) +In Angular, a [project](#project) that provides functionality that can be included in other Angular applications. +A library isn't a complete Angular application and can't run independently. +(To add re-usable Angular functionality to non-Angular web applications, you can use Angular [custom elements](#angular-element).) * Library developers can use the [Angular CLI](#cli) to `generate` scaffolding for a new library in an existing [workspace](#workspace), and can publish a library as an `npm` package. @@ -607,7 +607,7 @@ Compare to [NgModule](#ngmodule). ## ngcc Angular compatibility compiler. -If you build your app using [Ivy](#ivy), but it depends on libraries that have not been compiled with Ivy, the CLI uses `ngcc` to automatically update the dependent libraries to use Ivy. +If you build your application using [Ivy](#ivy), but it depends on libraries that have not been compiled with Ivy, the CLI uses `ngcc` to automatically update the dependent libraries to use Ivy. {@a ngmodule} @@ -723,7 +723,7 @@ An [injector](#injector) uses the provider to create a new instance of a depende for a class that requires it. Angular registers its own providers with every injector, for services that Angular defines. -You can register your own providers for services that your app needs. +You can register your own providers for services that your application needs. See also [service](#service), [dependency injection](#di). @@ -776,11 +776,11 @@ Learn more in the [Routing and Navigation](guide/router#preventing-unauthorized- ## router -A tool that configures and implements navigation among states and [views](#view) within an Angular app. +A tool that configures and implements navigation among states and [views](#view) within an Angular application. The `Router` module is an [NgModule](#ngmodule) that provides the necessary service providers and directives for navigating through application views. A [routing component](#routing-component) is one that imports the `Router` module and whose template contains a `RouterOutlet` element where it can display views produced by the router. -The router defines navigation among views on a single page, as opposed to navigation among pages. It interprets URL-like links to determine which views to create or destroy, and which components to load or unload. It allows you to take advantage of [lazy loading](#lazy-load) in your Angular apps. +The router defines navigation among views on a single page, as opposed to navigation among pages. It interprets URL-like links to determine which views to create or destroy, and which components to load or unload. It allows you to take advantage of [lazy loading](#lazy-load) in your Angular applications. To learn more, see [Routing and Navigation](guide/router). @@ -815,7 +815,7 @@ A schematic defines [rules](#rule) that operate on a virtual file system called The [Angular CLI](#cli) uses schematics to generate and modify [Angular projects](#project) and parts of projects. -* Angular provides a set of schematics for use with the CLI. See the [Angular CLI command reference](cli). The [`ng add`](cli/add) command runs schematics as part of adding a library to your project. The [`ng generate`](cli/generate) command runs schematics to create apps, libraries, and Angular code constructs. +* Angular provides a set of schematics for use with the CLI. See the [Angular CLI command reference](cli). The [`ng add`](cli/add) command runs schematics as part of adding a library to your project. The [`ng generate`](cli/generate) command runs schematics to create applications, libraries, and Angular code constructs. * [Library](#library) developers can create schematics that enable the Angular CLI to add and update their published libraries, and to generate artifacts the library defines. Add these schematics to the npm package that you use to publish and share your library. @@ -855,10 +855,10 @@ Import a scoped package in the same way that you import a normal package. A technique that generates static application pages on the server, and can generate and serve those pages in response to requests from browsers. It can also pre-generate pages as HTML files that you serve later. -This technique can improve performance on mobile and low-powered devices and improve the user experience by showing a static first page quickly while the client-side app is loading. -The static version can also make your app more visible to web crawlers. +This technique can improve performance on mobile and low-powered devices and improve the user experience by showing a static first page quickly while the client-side application is loading. +The static version can also make your application more visible to web crawlers. -You can easily prepare an app for server-side rendering by using the [CLI](#cli) to run the [Angular Universal](#universal) tool, using the `@nguniversal/express-engine` [schematic](#schematic). +You can easily prepare an application for server-side rendering by using the [CLI](#cli) to run the [Angular Universal](#universal) tool, using the `@nguniversal/express-engine` [schematic](#schematic). {@a service} @@ -1032,7 +1032,7 @@ A data flow model where the component tree is always checked for changes in one In practice, this means that data in Angular flows downward during change detection. A parent component can easily change values in its child components because the parent is checked first. A failure could occur, however, if a child component tries to change a value in its parent during change detection (inverting the expected data flow), because the parent component has already been rendered. -In development mode, Angular throws the `ExpressionChangedAfterItHasBeenCheckedError` error if your app attempts to do this, rather than silently failing to render the new value. +In development mode, Angular throws the `ExpressionChangedAfterItHasBeenCheckedError` error if your application attempts to do this, rather than silently failing to render the new value. To avoid this error, a [lifecycle hook](guide/lifecycle-hooks) method that seeks to make such a change should trigger a new change detection run. The new run follows the same direction as before, but succeeds in picking up the new value. @@ -1097,7 +1097,7 @@ A collection of Angular [projects](#project) (that is, applications and librarie The [CLI](#cli) [`ng new` command](cli/new) creates a file system directory (the "workspace root"). In the workspace root, it also creates the workspace [configuration file](#configuration) (`angular.json`) and, by default, an initial application project with the same name. -Commands that create or operate on apps and libraries (such as `add` and `generate`) must be executed from within a workspace folder. +Commands that create or operate on applications and libraries (such as `add` and `generate`) must be executed from within a workspace folder. For more information, see [Workspace Configuration](guide/workspace-config). @@ -1126,9 +1126,9 @@ For more information, see [Workspace and Project File Structure](guide/file-stru ## zone -An execution context for a set of asynchronous tasks. Useful for debugging, profiling, and testing apps that include asynchronous operations such as event processing, promises, and calls to remote servers. +An execution context for a set of asynchronous tasks. Useful for debugging, profiling, and testing applications that include asynchronous operations such as event processing, promises, and calls to remote servers. -An Angular app runs in a zone where it can respond to asynchronous events by checking for data changes and updating the information it displays by resolving [data bindings](#data-binding). +An Angular application runs in a zone where it can respond to asynchronous events by checking for data changes and updating the information it displays by resolving [data bindings](#data-binding). A zone client can take action before and after an async operation completes. diff --git a/aio/content/guide/styleguide.md b/aio/content/guide/styleguide.md index cd9af8f678..36f08420f4 100644 --- a/aio/content/guide/styleguide.md +++ b/aio/content/guide/styleguide.md @@ -24,7 +24,7 @@ On the other hand, you need a really unusual case for breaking a *Do* guideline.
**Consider** guidelines should generally be followed. -If you fully understand the meaning behind the guideline and have a good reason to deviate, then do so. Please strive to be consistent. +If you fully understand the meaning behind the guideline and have a good reason to deviate, then do so. Aim to be consistent.
@@ -55,7 +55,7 @@ The guideline uses the shortcut `hero.component.ts|html|css|spec` to represent t Apply the single responsibility principle (SRP) to all components, services, and other symbols. -This helps make the app cleaner, easier to read and maintain, and more testable. +This helps make the application cleaner, easier to read and maintain, and more testable. {@a 01-01} @@ -167,7 +167,7 @@ supporting classes into their own, dedicated files. -As the app grows, this rule becomes even more important. +As the application grows, this rule becomes even more important. Back to top @@ -306,7 +306,7 @@ Naming conventions are hugely important to maintainability and readability. This -**Why?** The naming conventions should simply help find desired code faster and make it easier to understand. +**Why?** The naming conventions should help find desired code faster and make it easier to understand.
@@ -840,7 +840,7 @@ As always, strive for consistency.
-**Do** put bootstrapping and platform logic for the app in a file named `main.ts`. +**Do** put bootstrapping and platform logic for the application in a file named `main.ts`.
@@ -852,7 +852,7 @@ As always, strive for consistency.
-**Avoid** putting app logic in `main.ts`. Instead, consider placing it in a component or service. +**Avoid** putting application logic in `main.ts`. Instead, consider placing it in a component or service.
@@ -933,19 +933,19 @@ For example, the prefix `toh` represents **T**our **o**f **H**eroes and the pref
-**Do** use a prefix that identifies the feature area or the app itself. +**Do** use a prefix that identifies the feature area or the application itself.
-**Why?** Prevents element name collisions with components in other apps and with native HTML elements. +**Why?** Prevents element name collisions with components in other applications and with native HTML elements.
-**Why?** Makes it easier to promote and share the component in other apps. +**Why?** Makes it easier to promote and share the component in other applications.
@@ -1636,9 +1636,9 @@ A consistent class and file name convention make these modules easy to spot and ## Application structure and NgModules -Have a near-term view of implementation and a long-term vision. Start small but keep in mind where the app is heading down the road. +Have a near-term view of implementation and a long-term vision. Start small but keep in mind where the application is heading. -All of the app's code goes in a folder named `src`. +All of the application's code goes in a folder named `src`. All feature areas are in their own folder, with their own NgModule. All content is one asset per file. Each component, service, and pipe is in its own file. @@ -1658,7 +1658,7 @@ Use the naming conventions for files in this guide. -**Do** structure the app such that you can **L**ocate code quickly, +**Do** structure the application such that you can **L**ocate code quickly, **I**dentify the code at a glance, keep the **F**lattest structure you can, and **T**ry to be DRY. @@ -1703,7 +1703,7 @@ _can I quickly open and start work in all of the related files for this feature_ -**Do** make locating code intuitive, simple, and fast. +**Do** make locating code intuitive and fast.
@@ -1904,7 +1904,7 @@ But if something is not obvious or departs from a convention, then spell it out. -**Do** start small but keep in mind where the app is heading down the road. +**Do** start small but keep in mind where the application is heading down the road. @@ -1926,7 +1926,7 @@ But if something is not obvious or departs from a convention, then spell it out. -**Do** put all of the app's code in a folder named `src`. +**Do** put all of the application's code in a folder named `src`. @@ -1948,7 +1948,7 @@ But if something is not obvious or departs from a convention, then spell it out. -**Why?** Helps keep the app structure small and easy to maintain in the early stages, while being easy to evolve as the app grows. +**Why?** Helps keep the application structure small and easy to maintain in the early stages, while being easy to evolve as the application grows. @@ -1959,7 +1959,7 @@ But if something is not obvious or departs from a convention, then spell it out. -**Why?** Components often have four files (e.g. `*.html`, `*.css`, `*.ts`, and `*.spec.ts`) and can clutter a folder quickly. +**Why?** Components often have four files (for example, `*.html`, `*.css`, `*.ts`, and `*.spec.ts`) and can clutter a folder quickly. @@ -2201,7 +2201,7 @@ Here is a compliant folder and file structure: While components in dedicated folders are widely preferred, -another option for small apps is to keep components flat (not in a dedicated folder). +another option for small applications is to keep components flat (not in a dedicated folder). This adds up to four files to the existing folder, but also reduces the folder nesting. Whatever you choose, be consistent. @@ -2238,7 +2238,7 @@ at a glance. The structure is as flat as it can be and there are no repetitive o
-**Why?** Helps reduce the app from becoming cluttered through organizing the +**Why?** Helps reduce the application from becoming cluttered through organizing the content and keeping them aligned with the LIFT guidelines.
@@ -2290,7 +2290,7 @@ and more difficult in a flat structure. -**Do** create an NgModule in the app's root folder, +**Do** create an NgModule in the application's root folder, for example, in `/src/app`. @@ -2302,7 +2302,7 @@ for example, in `/src/app`. -**Why?** Every app requires at least one root NgModule. +**Why?** Every application requires at least one root NgModule. @@ -3195,7 +3195,7 @@ helps instantly identify which members of the component serve which purpose. -**Why?** Logic may be reused by multiple components when placed within a service and exposed via a function. +**Why?** Logic may be reused by multiple components when placed within a service and exposed as a function. @@ -3651,7 +3651,7 @@ Compare with the less preferred `host` metadata alternative. -**Do** provide a service with the app root injector in the `@Injectable` decorator of the service. +**Do** provide a service with the application root injector in the `@Injectable` decorator of the service.