diff --git a/public/docs/ts/latest/guide/style-guide.jade b/public/docs/ts/latest/guide/style-guide.jade
index 312cdea64c..bdddecebeb 100644
--- a/public/docs/ts/latest/guide/style-guide.jade
+++ b/public/docs/ts/latest/guide/style-guide.jade
@@ -1,15 +1,29 @@
include ../_util-fns
:marked
- Welcome to the Angular Style Guide
-
- ## Purpose
-
Looking for an opinionated guide to Angular syntax, conventions, and application structure?
Step right in!
- This style guide presents our preferred conventions and, as importantly, explains why.
-.l-main-section
+ This style guide presents preferred conventions and, as importantly, explains why.
+.l-main-section
+a(id='toc')
+
+:marked
+ # Contents
+
+ * [Single responsibility](#single-responsibility)
+ * [Naming](#naming)
+ * [Coding conventions](#coding-conventions)
+ * [App structure and Angular modules](#application-structure-and-angular-modules)
+ * [Components](#components)
+ * [Directives](#directives)
+ * [Services](#services)
+ * [Data services](#data-services)
+ * [Lifecycle hooks](#lifecycle-hooks)
+ * [Appendix](#appendix)
+
+
+.l-main-section
:marked
## Style vocabulary
@@ -32,6 +46,11 @@ include ../_util-fns
.s-rule.avoid
:marked
**Avoid** indicates something you should almost never do. Code examples to *avoid* have an unmistakeable red header.
+
+.s-why
+ :marked
+ **Why?** gives reasons for following the previous recommendations.
+
.l-main-section
:marked
@@ -40,37 +59,20 @@ include ../_util-fns
Some code examples display a file that has one or more similarly named companion files.
For example, `hero.component.ts` and `hero.component.html`.
- The guideline will use the shortcut `hero.component.ts|html|css|spec` to represent those various files. Using this shortcut makes this guide's file structures easier to read and more terse.
-
-.l-main-section
-a(id='toc')
-
-:marked
- ## Table of contents
-
- 1. [Single responsibility](#single-responsibility)
- 1. [Naming](#naming)
- 1. [Coding conventions](#coding-conventions)
- 1. [App structure and Angular modules](#application-structure-and-angular-modules)
- 1. [Components](#components)
- 1. [Directives](#directives)
- 1. [Services](#services)
- 1. [Data services](#data-services)
- 1. [Lifecycle hooks](#lifecycle-hooks)
- 1. [Appendix](#appendix)
+ The guideline uses the shortcut `hero.component.ts|html|css|spec` to represent those various files. Using this shortcut makes this guide's file structures easier to read and more terse.
.l-main-section
+a#single-responsibility
:marked
## Single responsibility
Apply the
- Single Responsibility Principle (SRP)
+ 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.
-a#rule-of-one
-:marked
- ### _Rule of One_
+
+ ### Rule of One
#### Style 01-01
.s-rule.do
:marked
@@ -95,7 +97,9 @@ a#rule-of-one
:marked
The key is to make the code more reusable, easier to read, and less mistake prone.
- The following *negative* example defines the `AppComponent`, bootstraps the app, defines the `Hero` model object, and loads heroes from the server ... all in the same file. *Don't do this*.
+ The following *negative* example defines the `AppComponent`, bootstraps the app,
+ defines the `Hero` model object, and loads heroes from the server all in the same file.
+ *Don't do this*.
+makeExample('style-guide/ts/src/01-01/app/heroes/hero.component.avoid.ts', '', 'app/heroes/hero.component.ts')(avoid=1)
:marked
@@ -349,12 +353,12 @@ a(href="#toc") Back to top
.s-rule.do
:marked
- **Do** suffix a service class name with Service.
+ **Do** suffix a service class name with `Service`.
For example, something that gets data or heroes
should be called a `DataService` or a `HeroService`.
A few terms are unambiguously services. They typically
- indicate agency by ending in "er". You may prefer to name
+ indicate agency by ending in "-er". You may prefer to name
a service that logs messages `Logger` rather than `LoggerService`.
Decide if this exception is agreeable in your project.
As always, strive for consistency.
@@ -421,7 +425,7 @@ a(href="#toc") Back to top
.s-rule.avoid
:marked
- **Avoid** putting app logic in the `main.ts`. Instead, consider placing it in a component or service.
+ **Avoid** putting app logic in `main.ts`. Instead, consider placing it in a component or service.
.s-why
:marked
@@ -451,7 +455,7 @@ a(href="#toc") Back to top
.s-why.s-why-last
:marked
- **Why?** The Angular HTML parser is case sensitive and will recognize lower camel case.
+ **Why?** The Angular HTML parser is case sensitive and recognizes lower camel case.
a(href="#toc") Back to top
@@ -659,7 +663,7 @@ table(width="100%")
tr(style=top)
td
:marked
- End to End Tests
+ End-to-End Tests
td
:marked
app.e2e-spec.ts
@@ -765,7 +769,7 @@ a(href="#toc") Back to top
:marked
## Coding conventions
- Have consistent set of coding, naming, and whitespace conventions.
+ Have a consistent set of coding, naming, and whitespace conventions.
.l-main-section
:marked
@@ -824,7 +828,7 @@ a(href="#toc") Back to top
:marked
**Why?** The tradition of naming constants in UPPER_SNAKE_CASE reflects
an era before the modern IDEs that quickly reveal the `const` declaration.
- TypeScript itself prevents accidental reassignment.
+ TypeScript prevents accidental reassignment.
.s-rule.do
:marked
@@ -906,7 +910,7 @@ a(href="#toc") Back to top
.s-why.s-why-last
:marked
- **Why?** TypeScript tooling makes it easy to identify private vs public properties and methods.
+ **Why?** TypeScript tooling makes it easy to identify private vs. public properties and methods.
+makeExample('style-guide/ts/src/03-04/app/core/toast.service.avoid.ts', 'example', 'app/shared/toast.service.ts')(avoid=1)
:marked
@@ -972,10 +976,10 @@ a(href="#toc") Back to top
.s-rule.do
:marked
- **Do** structure the app 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.
+ **Do** structure the app 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.
.s-rule.do
:marked
@@ -1000,8 +1004,7 @@ a(href="#toc") Back to top
.s-why.s-why-last
:marked
- **Why?**
- To work efficiently you must be able to find files quickly,
+ **Why?** To work efficiently you must be able to find files quickly,
especially when you do not know (or do not remember) the file _names_.
Keeping related files near each other in an intuitive location saves time.
A descriptive folder structure makes a world of difference to you and the people who come after you.
@@ -1077,7 +1080,7 @@ a(href="#toc") Back to top
.s-rule.do
:marked
- **Do** be DRY (Don't Repeat Yourself)
+ **Do** be DRY (Don't Repeat Yourself).
.s-rule.avoid
:marked
@@ -1087,7 +1090,8 @@ a(href="#toc") Back to top
:marked
**Why?** Being DRY is important, but not crucial if it sacrifices the other elements of LIFT.
That's why it's called _T-DRY_.
- For example, it's redundant to name a component, `hero-view.component.html` because a component is obviously a view.
+ For example, it's redundant to name a template `hero-view.component.html` because
+ with the `.html` extension, it is obviously a view.
But if something is not obvious or departs from a convention, then spell it out.
a(href="#toc") Back to top
@@ -1203,8 +1207,8 @@ a(href="#toc") Back to top
.s-why
:marked
- **Why?** A developer can locate the code, identify what each file represents
- at a glance, the structure is as flat as it can be, and there are no repetitive or redundant names.
+ **Why?** A developer can locate the code and identify what each file represents
+ at a glance. The structure is as flat as it can be and there are no repetitive or redundant names.
.s-why
:marked
@@ -1212,11 +1216,14 @@ a(href="#toc") Back to top
.s-why
:marked
- **Why?** Helps reduce the app from becoming cluttered through organizing the content and keeping them aligned with the LIFT guidelines.
+ **Why?** Helps reduce the app from becoming cluttered through organizing the
+ content and keeping them aligned with the LIFT guidelines.
.s-why
:marked
- **Why?** When there are a lot of files (e.g. 10+), locating them is easier with a consistent folder structure and more difficult in a flat structure.
+ **Why?** When there are a lot of files, for example 10+,
+ locating them is easier with a consistent folder structure
+ and more difficult in a flat structure.
.s-rule.do
:marked
@@ -1243,7 +1250,8 @@ a(href="#toc") Back to top
.s-rule.do
:marked
- **Do** create an Angular module in the app's root folder (e.g., in `/src/app`).
+ **Do** create an Angular module in the app's root folder,
+ for example, in `/src/app`.
.s-why
:marked
@@ -1269,19 +1277,23 @@ a(href="#toc") Back to top
.s-rule.do
:marked
- **Do** create an Angular module for all distinct features in an application (e.g. `Heroes` feature).
+ **Do** create an Angular module for all distinct features in an application;
+ for example, a `Heroes` feature.
.s-rule.do
:marked
- **Do** place the feature module in the same named folder as the feature area (.e.g `app/heroes`).
+ **Do** place the feature module in the same named folder as the feature area;
+ for example, in `app/heroes`.
.s-rule.do
:marked
- **Do** name the feature module file reflecting the name of the feature area and folder (e.g. `app/heroes/heroes.module.ts`)
+ **Do** name the feature module file reflecting the name of the feature area
+ and folder; for example, `app/heroes/heroes.module.ts`.
.s-rule.do
:marked
- **Do** name the feature module symbol reflecting the name of the feature area, folder, and file (e.g. `app/heroes/heroes.module.ts` defines `HeroesModule`)
+ **Do** name the feature module symbol reflecting the name of the feature
+ area, folder, and file; for example, `app/heroes/heroes.module.ts` defines `HeroesModule`.
.s-why
:marked
@@ -1316,7 +1328,8 @@ a(href="#toc") Back to top
.s-rule.do
:marked
- **Do** create a feature module named `SharedModule` in a `shared` folder (e.g. `app/shared/shared.module.ts` defines `SharedModule`).
+ **Do** create a feature module named `SharedModule` in a `shared` folder;
+ for example, `app/shared/shared.module.ts` defines `SharedModule`.
.s-rule.do
:marked
@@ -1325,7 +1338,7 @@ a(href="#toc") Back to top
.s-rule.consider
:marked
- **Consider** using the name SharedModule, when the contents of a shared
+ **Consider** using the name SharedModule when the contents of a shared
module are referenced across the entire application.
.s-rule.do
@@ -1336,11 +1349,14 @@ a(href="#toc") Back to top
.s-rule.do
:marked
- **Do** import all modules required by the assets in the `SharedModule` (e.g. `CommonModule` and `FormsModule`).
+ **Do** import all modules required by the assets in the `SharedModule`;
+ for example, `CommonModule` and `FormsModule`.
.s-why
:marked
- **Why?** `SharedModule` will contain components, directives and pipes that may need features from another common module (e.g. `ngFor` in `CommonModule`).
+ **Why?** `SharedModule` will contain components, directives and pipes
+ that may need features from another common module; for example,
+ `ngFor` in `CommonModule`.
.s-rule.do
:marked
@@ -1642,7 +1658,7 @@ a(href="#toc") Back to top
:marked
**Why?** components have templates containing HTML and optional Angular template syntax.
They display content.
- Developers place components on the page as they would native HTML elements and WebComponents.
+ Developers place components on the page as they would native HTML elements and web components.
.s-why.s-why-last
:marked
@@ -1726,7 +1742,7 @@ a(href="#toc") Back to top
.s-rule.do
:marked
- **Do** use the `@Input` and `@Output` class decorators instead of the `inputs` and `outputs` properties of the
+ **Do** use the `@Input()` and `@Output()` class decorators instead of the `inputs` and `outputs` properties of the
`@Directive` and `@Component` metadata:
.s-rule.do
@@ -1937,7 +1953,7 @@ a(href="#toc") Back to top
.s-why
:marked
- **Why?** Attributes directives don't have an associated template.
+ **Why?** Attribute directives don't have an associated template.
.s-why.s-why-last
:marked
@@ -1968,7 +1984,7 @@ a(href="#toc") Back to top
.s-why.s-why-last
:marked
**Why?** The property associated with `@HostBinding` or the method associated with `@HostListener`
- can be modified only in a single place - in the directive's class.
+ can be modified only in a single place—in the directive's class.
If you use the `host` metadata property, you must modify both the property declaration inside the controller,
and the metadata associated with the directive.
@@ -2075,7 +2091,7 @@ a(href="#toc") Back to top
.s-rule.do
:marked
- **Do** use the `@Injectable` class decorator instead of the `@Inject` parameter decorator when using types as tokens for the dependencies of a service.
+ **Do** use the `@Injectable()` class decorator instead of the `@Inject` parameter decorator when using types as tokens for the dependencies of a service.
.s-why
:marked