docs(upgrade): updates based on review comments. preliminary description of DOM in hybrid apps.

Author: teropa

public/docs/ts/latest/upgrade/index.jade

@@ -17,7 +17,7 @@ include ../../../../_includes/_util-fns
 
   One of the keys to a successful upgrade is to do it incrementally,
   by running the two frameworks side by side in the same application, and
-  porting Angular 1 components to Angular 1 one by one. This makes it possible
+  porting Angular 1 components to Angular 2 one by one. This makes it possible
   to upgrade even large and complex applications without disrupting other
   business, because the work can be done collaboratively and spread over
   a period of time. The [upgrade module in Angular 2](upgrade_adapter.html)

public/docs/ts/latest/upgrade/preparation.jade

@@ -54,19 +54,19 @@ include ../../../../_includes/_util-fns
   about during the upgrade. It also means we can start using TypeScript features
   in our Angular 1 code.
 
-  Since TypeScript is a superset of ECMAScript 6, which in turn is a superset
+  Since TypeScript is a superset of ECMAScript 2015, which in turn is a superset
   of ECMAScript 5, switching to TypeScript doesn't necessarily mean anything
   else than intalling the TypeScript compiler and switching the extensions from
   `.js` to `.ts`. Just doing that is not hugely exciting though. The following
   steps will give us much more bang for the buck:
 
   * For applications that use a module loader, TypeScript imports and exports
-    (which are really ECMAScript 6 imports and exports) can be used to organize
+    (which are really ECMAScript 2015 imports and exports) can be used to organize
     code into modules. 
   * Type annotations can be gradually added to existing functions and variables
     to pin down their types and get all the benefits that brings, from built-time
     error checking to autocompletion and inline documentation.
-  * ES6 features like `let`s and `const`s, default function parameters,
+  * ES2015 features like `let`s and `const`s, default function parameters,
     and destructuring assignments can also be gradually added.
   * Services and Controller can be turned into *classes*. That way they'll be a step
     closer to becoming Angular 2 service component classes, which will make our life

public/docs/ts/latest/upgrade/tutorial.jade

@@ -90,7 +90,7 @@ include ../../../../_includes/_util-fns
   Since we're going to be writing our Angular 2 code in TypeScript, it makes sense to
   bring in the TypeScript compiler even before we begin upgrading.
 
-  In order to use TypeScript's ES6 module system to `import` and `export` code, we're
+  In order to use TypeScript's ES2015 module system to `import` and `export` code, we're
   going to need a JavaScript module loader. Our application doesn't currently
   use one, and is just using plain old `<script>` tags and the global `window` scope
   instead. We'll replace this approach with the
@@ -135,8 +135,9 @@ include ../../../../_includes/_util-fns
   module using `System.import`. This will load and execute the `app/app.js` file.
 
   We should also configure the TypeScript compiler so that it can understand our
-  project. Add a `tsconfig.json` file to the `src` directory. It instructs the
-  TypeScript compiler how to interpret our source files.
+  project. We'll add a `tsconfig.json` file to the `src` directory, just like we did
+  in the [Quickstart](../quickstart.html). It instructs the TypeScript compiler how
+  to interpret our source files.
 
 +makeJson('upgrade/ts/typescript-conversion/src/tsconfig.json', null, 'src/tsconfig.json')
 
@@ -165,7 +166,7 @@ include ../../../../_includes/_util-fns
   departure from the previous approach which just relied on things being available
   on the global `window` scope.
 
-  Since TypeScript is a superset of ECMAScript 6, which in turn is a superset
+  Since TypeScript is a superset of ECMAScript 2015, which in turn is a superset
   of ECMAScript 5, we can simply switch the file extensions from `.js` to `.ts`
   and define the imports and exports. We don't need to make other changes to
   our existing code. Instead we'll introduce type annotations and other new
@@ -377,9 +378,9 @@ include ../../../../_includes/_util-fns
   other features in addition to the imports and exports that we're already using.
   There's a lot of value the language can provide in Angular 1 applications.
 
-  For one thing, TypeScript is a superset of ES6. Any app that has previously
+  For one thing, TypeScript is a superset of ES2015. Any app that has previously
   been written in ES5 - like the PhoneCat example has - can with TypeScript
-  start incorporating all of the JavaScript features that are new to ES6.
+  start incorporating all of the JavaScript features that are new to ES2015.
   These include things like `let`s and `const`s, default function parameters,
   and destructuring assignments.
 
@@ -413,7 +414,7 @@ include ../../../../_includes/_util-fns
   easier once we do the upgrade.
 
   Angular 1 expects controllers to be constructor functions, and that's what
-  ES6/TypeScript classes really are, and that means we can just register a
+  ES2015/TypeScript classes really are, and that means we can just register a
   class as a controller and Angular 1 will happily use it. We also won't 
   need to make any changes to our test suite as the external behavior of the
   controllers will not change.
@@ -426,10 +427,10 @@ include ../../../../_includes/_util-fns
   What was previously done in the controller function is now done in the class
   constructor function. The class additionally declares three members: The 
   array of phones, the name of the current sort key, and the search query. These
-  are all things we we're attaching to `this`/`vm` earlier, but that weren't
-  explicitly declared anywhere. The last one of these isn't actually used in the
-  TypeScript code since it's only referred to in the template, but for the sake
-  of clarity we want to define all the members our controller will have.
+  are all things we have already been attaching to the controller,
+  but that weren't explicitly declared anywhere. The last one of these isn't actually
+  used in the TypeScript code since it's only referred to in the template, but for
+  the sake of clarity we want to define all the members our controller will have.
 
   In the Phone detail controller we'll have two members: One for the phone
   that the user is looking at and another for the URL of the currently displayed image.
@@ -443,6 +444,14 @@ include ../../../../_includes/_util-fns
 :marked
   This makes our controller code look a lot more like Angular 2 already. We're
   all set to actually introduce Angular 2 into the project.
+  
+  If we had any Angular 1 services in the project, those would also be
+  a good candidate for converting to classes, since like controllers,
+  they're also constructor functions. But we only have the `Phone` factory
+  in this project, and that's a bit special since it's an `ngResource`
+  factory. So we won't be doing anything to it in the preparation stage,
+  but will instead turn it directly into an Angular 2 service in the
+  next section.
 
 .l-main-section
 :marked
@@ -537,8 +546,9 @@ include ../../../../_includes/_util-fns
 +makeExample('upgrade/ts/ng2_initial/src/app/app.ts', 'bootstrap')
 
 :marked
-  We are now running both Angular 1 and 2 at the same time, though there are
-  no Angular 2 components in it yet.
+  We are now running both Angular 1 and 2 at the same time. That's pretty
+  exciting! We're not running any actual Angular 2 components yet though,
+  so let's do that next.
 
 
 :marked
@@ -595,9 +605,10 @@ include ../../../../_includes/_util-fns
 
 :marked
   The `@Injectable` decorator will attach some dependency injection metadata
-  to the class, letting Angular 2 know about its dependencies. This is
-  a marker decorator we need to use for classes that have no other Angular 2
-  decorators but still need to have their dependencies injected.
+  to the class, letting Angular 2 know about its dependencies. As described
+  by our [Dependency Injection Guide](../guide/dependency-injection.html),
+  this is a marker decorator we need to use for classes that have no other
+  Angular 2 decorators but still need to have their dependencies injected. 
 
   In its constructor the class expects to get the `Http` service. It will
   be injected to it and it is stored as a private field. The service is then
@@ -806,9 +817,16 @@ include ../../../../_includes/_util-fns
   These pipes do not exist in Angular 2, so we're going to need to do
   the filtering and sorting ourselves. Let's define a couple of pipes that
   get the job done.
-  
+
+.alert.is-helpful
+  :marked
+    If you want to learn more about how pipes in Angular 2
+    work, we have [a whole guide on the subject](../guide/pipes.html)
+    available!
+    
+:marked
   For filtering, we'll have a pipe called `PhoneFilterPipe`. It works like 
-  `filter` in Angular 1 in that it filters a collection of objects,
+  the `filter` filter in Angular 1 in that it filters a collection of objects,
   matching properties within the objects. But, as opposed to `filter`,
   this pipe is specialized to filter `Phone` objects and we can use
   type annotations to make this explicit:
@@ -858,7 +876,7 @@ include ../../../../_includes/_util-fns
 
 :marked
   This is made possible by the `async` pipe, which we can apply in the template.
-  I knows how to turn an Observable to the (latest) value it has emitted:
+  It knows how to turn an Observable to the (latest) value it has emitted:
 
 +makeExample('upgrade/ts/ng2_components/src/app/phone_list/phone_list.html', 'list', 'src/app/phone_list/phone_list.html')
 

public/docs/ts/latest/upgrade/upgrade_adapter.jade

@@ -68,9 +68,65 @@ table
     be downgraded. Again, the same singleton instances are shared. As you register the
     downgrade, you will explicitly specify a *string token* to be used in Angular 1.
 
-  ### Components and DOM
+.alert.is-helpful Mention provider upgrades/downgrades
+
+:marked
+  ### Components and the DOM
+
+  What we'll find in the DOM of a hybrid application are components and
+  directives both from Angular 1 and Angular 2. These components
+  communicate with each other by using the input and output bindings
+  of their respective frameworks, which the `UpgradeAdapter` bridges
+  together. They may also communicate through shared injected dependencies,
+  as described above.
+  
+  There are two key things to understand about what happens in the DOM
+  of a hybrid application:
+
+  1. Every element in the DOM is owned by exactly one of the two
+     frameworks. The other framework ignores it. If an element is
+     owned by Angular 1, Angular 2 treats it as if it didn't exist,
+     and vice versa.
+  2. The root of the application *is always an Angular 1 template*.
+
+  So a hybrid application begins life as an Angular 1 application,
+  and it is Angular 1 that processes its root template. How Angular 2 then steps
+  into the picture is when somewhere in the Angular 1 application's
+  templates an Angular 2 component is used. That component's view will
+  then be managed by Angular 2, and may use any number of Angular 2
+  components and directives.
+  
+  After that, we may interleave the two frameworks as much as we need to,
+  and we cross the boundary between the two frameworks by two alternative
+  ways:
+  
+  1. By using a component from the other framework: An Angular 1 template
+     using an Angular 2 component, or an Angular 2 template using an
+     Angular 1 component.
+  2. By transcluding or projecting content from the other framework. When
+     an Angular 1 template uses an Angular 2 component, it may *transclude*
+     content into it. The Angular 2 component then uses Angular 2 *content
+     projection* to attach it somewhere. The `UpgradeAdapter` bridges
+     Angular 1 transclusion to Angular 2 content projection, and vice versa.
+  
+  Whenever you use a component that belongs to the other framework, a 
+  switch between framework boundaries occurs. However, that switch only
+  happens to the *children* of the component element. When you use an
+  Angular 2 component from Angular 1 like this:
+  
+  ```
+  <ng2-component></ng2-component>
+  ```
+  
+  The element `ng2-component` will remain to be an Angular 1 managed
+  element, because it's defined in an Angular 1 template. That also
+  means you can apply additional Angular 1 directives to it, but not
+  Angular 2 directives. It is in the view of the `Ng2Component` component,
+  where Angular 2 is used, so the child elements of `ng2-component` will
+  live in Angular 2 land.
 
-.alert.is-helpful On component adapters. Element ownership. Transclusion / content projection.
+  This same rule also applies when you use Angular 1 component directives
+  from Angular 2.
 
 :marked
   ### Change Detection