docs(template-syntax/structural-directives): Add edits and comments on structural-directives

Author: kapunahelewong

public/docs/ts/latest/guide/structural-directives.jade

@@ -27,6 +27,15 @@ style.
 
   Try the <live-example></live-example>.
 
+.alert.is-helpful
+  :marked
+     `NgFor` and `ngFor` appear throughout the Angular documentation 
+     and you may wonder what the difference is. The _directive_ name is `NgFor`. 
+     Its _usage in a template_ is `ngFor`. This is critical in 
+     differentiating between the *context* of the directive or 
+     a *property* of the directive.  `NgFor` has a `NgForTrackBy` 
+     property. The attribute `ngFor` doesn't have any properties.
+
 a#definition
 .l-main-section
 :marked
@@ -49,9 +58,10 @@ a#definition
   You'll learn in this guide that the [asterisk (\*) is a convenience syntax](#asterisk). Angular "de-sugars" it into a `<template>` around the
   host element and its descendents. Each structural directive does something different with that template.
 
-  Three of the common, built-in structural directives &mdash; 
-  [NgIf](template-syntax.html#ngIf), [NgFor](template-syntax.html#ngFor), and [NgSwitch...](template-syntax.html#ngSwitch) &mdash;
-  are described in the [_Template Syntax_](template-syntax.html) guide and seen in samples throughout the Angular documentation.
+  Three of the common, built-in structural directives&mdash;[NgIf](template-syntax.html#ngIf), 
+  [NgFor](template-syntax.html#ngFor), and [NgSwitch...](template-syntax.html#ngSwitch)&mdash;are 
+  described in the [_Template Syntax_](template-syntax.html) guide and seen in samples throughout the Angular documentation. 
+  Here's an example of them in a template:
 
 +makeExample('structural-directives/ts/app/app.component.html', 'built-in')(format=".")
 :marked
@@ -84,7 +94,7 @@ a#ngIf
   ## NgIf Case Study
 
   `NgIf` is the simplest structural directive and the easiest to understand.
-  It takes a boolean value and makes an entire chunk of DOM appear or disappear.
+  It takes a boolean value and makes an entire chunk of the DOM appear or disappear.
 
 <<<<<<< dc4da634c40560e4eda55814676bc96a230428dc
 +makeExample('structural-directives/ts/src/app/structural-directives.component.html', 'ngIf')(format=".")
@@ -103,9 +113,9 @@ figure.image-display
   The top paragraph is in the DOM. The bottom, disused paragraph is not; 
   in its place is a comment about "template bindings" (more about that [later](#asterisk)).
 
-  When the condition is false, `NgIf` removes its host element from DOM,
-  detaches it from DOM events (the attachments that it made)
-  detaches the component from Angular change detection and destroys it.
+  When the condition is false, `NgIf` removes its host element from the DOM,
+  detaches it from DOM events (the attachments that it made),
+  detaches the component from Angular change detection, and destroys it.
   The component and DOM nodes can be garbage-collected and free up memory.
 
   ### Why *remove* rather than *hide*?
@@ -126,20 +136,20 @@ figure.image-display
   Angular keeps checking for changes that could affect data bindings.
   Whatever the component was doing, it keeps doing.
 
-  Although invisible, the component &mdash; and all of its descendant components &mdash; tie up resources.
+  Although invisible, the component&mdash;and all of its descendant components&mdash;tie up resources.
   The performance and memory burden can be substantial, responsiveness can degrade, and the user sees nothing.
 
   On the positive side, showing the element again is quick.
   The component's previous state is preserved and ready to display.
-  The component doesn't re-initialize &mdash; an operation that could be expensive.
+  The component doesn't re-initialize&mdash;an operation that could be expensive.
   So hiding and showing is sometimes the right thing to do.
 
   But in the absence of a compelling reason to keep them around, 
   your preference should be to remove DOM elements that the user can't see
   and recover the unused resources with a structural directive like `NgIf` .
 
   **These same considerations apply to every structural directive, whether built-in or custom.**
-  We should ask ourselves &mdash; and the users of our directives &mdash; to think carefully
+  We should ask ourselves&mdash;and the users of our directives&mdash;to think carefully
   about the consequences of adding and removing elements and of creating and destroying components.
 
 a#ngcontainer
@@ -168,16 +178,16 @@ a#ng-container
 +makeExample('structural-directives/ts/app/app.component.html', 'ngif')(format=".")
 
 :marked
-  Introducing another container element &mdash; typically a `<span>` or `<div>` &mdash;
-  to group the elements under a single _root_ is usually harmless. 
+  Introducing another container element&mdash;typically a `<span>` or `<div>`&mdash;to 
+  group the elements under a single _root_ is usually harmless. 
   _Usually_ ... but not _always_.
 
   The grouping element may break the template appearance because CSS styles 
   neither expect nor accommodate the new layout.
   For example, suppose you have the following paragraph layout.
 +makeExample('structural-directives/ts/app/app.component.html', 'ngif-span')(format=".")
 :marked
-  You also have a CSS style rule that happens to apply to a `<span>` within `<p>`aragraph.
+  You also have a CSS style rule that happens to apply to a `<span>` within a `<p>`aragraph.
 +makeExample('structural-directives/ts/app/app.component.css', 'p-span')(format=".")
 :marked
   The constructed paragraph renders strangely.
@@ -286,7 +296,7 @@ a#ngfor
   Angular transforms the `*ngFor` in similar fashion from asterisk (\*) syntax through
   template _attribute_ to template _element_. 
 
-  Here's a full-featured `ngFor`, written all three ways
+  Here's a full-featured `ngFor`, written all three ways:
 +makeExample('structural-directives/ts/app/app.component.html', 'inside-ngfor')(format=".")
 
 <<<<<<< dc4da634c40560e4eda55814676bc96a230428dc
@@ -296,7 +306,7 @@ a#ngfor
 >>>>>>> docs(template-syntax/structural-directives): refresh both guides for style, accuracy, understanding
 :marked
   This is manifestly more complicated than `ngIf` and rightly so.
-  `NgFor` directive has more features, both required and optional, than the `NgIf` shown in this guide.
+  The `ngFor` directive has more features, both required and optional, than the `NgIf` shown in this guide.
   At minimum `NgFor` needs a looping variable (`let hero`) and a list (`heroes`).
 
   You enable these features in the string assigned to `ngFor`, which you write in Angular's [microsyntax](microsyntax). 
@@ -326,6 +336,14 @@ a#microsyntax
   The `NgFor` directive sets its _context's_ `$implicit` property to the current item in the list during each iteration.
   That becomes the current value of the `hero` variable in the example above.
 
+.alert.is-critical
+   :marked
+     Ward: I got lost on this third point. ^^ By context, do we mean the element that the 
+      directive is on, such as the `<div>`? Next, I was thrown by `$implicit`. What is that? 
+      Obviously a property, but why the `$` and should I know more about properties of 
+      contexts? Can we link to something for more info? I felt like this was touching 
+      on deep stuff.
+:marked
   * The other _let_ variables (`i` and `odd`) are linked to one of the directive's _named context_ properties.
   Look to the directive's documentation to see which properties are available and what they do. 
   `NgFor` has several, including `index` and `odd`.
@@ -385,13 +403,17 @@ a#ngswitch
 :marked
   ## Inside the _NgSwitch_ directives
 
+<<<<<<< a5705eb367d80adf19abf765d735b9d1189b52e6
 <<<<<<< dc4da634c40560e4eda55814676bc96a230428dc
 +makeExample('structural-directives/ts/src/app/structural-directives.component.html', 'asterisk')(format=".")
 :marked
   We're prefixing these directive names with an asterisk (\*).
 =======
   The Angular _NgSwitch_ is actally a set of cooperating directives: `NgSwitch`, `NgSwitchCase`, and `NgSwitchDefault`.
 >>>>>>> docs(template-syntax/structural-directives): refresh both guides for style, accuracy, understanding
+=======
+  The Angular _NgSwitch_ is actually a set of cooperating directives: `NgSwitch`, `NgSwitchCase`, and `NgSwitchDefault`.
+>>>>>>> docs(template-syntax/structural-directives): Add edits and comments on structural-directives
 
   Here's an example.
 +makeExample('structural-directives/ts/app/app.component.html', 'ngswitch')(format=".")
@@ -409,6 +431,13 @@ a#ngswitch
   `NgSwitchDefault` includes its host element when no `NgSwitchCase` does.
 >>>>>>> docs(template-syntax/structural-directives): refresh both guides for style, accuracy, understanding
 
+.alert.is-critical
+  :marked
+    Ward: I was following along until these last two sentences above ^^. What does 
+    "includes its host element" mean? Possibly in the same way we mean when we say 
+    that something is in an include?
+
+:marked
   As with other structural directives, the `NgSwitchCase` and `NgSwitchDefault` 
   can be "de-sugared" into the template _attribute_ form.
 +makeExample('structural-directives/ts/app/app.component.html', 'ngswitch-template-attr')(format=".")
@@ -461,7 +490,7 @@ a#unless
   ## Write a structural directive
   In this section, you write a `MyUnless` directive structural directive
   that does the opposite of `NgIf`.
-  `NgIf` displays the template content when the condition `true`.
+  `NgIf` displays the template content when the condition is `true`.
   `MyUnless` displays the content when the condition is ***false***.
 
 +makeExample('structural-directives/ts/app/app.component.html', 'myUnless-1')(format=".")
@@ -503,9 +532,18 @@ block unless-intro
   Pick something short that fits you or your company.
   In this example, the prefix is `my`.
 
+<<<<<<< a5705eb367d80adf19abf765d735b9d1189b52e6
 <<<<<<< dc4da634c40560e4eda55814676bc96a230428dc
 +makeExample('structural-directives/ts/src/app/unless.directive.ts', 'unless-constructor')(format=".")
 =======
+=======
+.alert.is-critical
+  :marked
+    Ward: Why is this called a *key* when it looks like the value in a 
+    key value pair?^^
+
+:marked
+>>>>>>> docs(template-syntax/structural-directives): Add edits and comments on structural-directives
   The directive _class_ name ends in `Directive` per the [style guide](style-guide.html#02-03 "Angular Style Guide").
   Angular's own directives do not.
 >>>>>>> docs(template-syntax/structural-directives): refresh both guides for style, accuracy, understanding
@@ -545,16 +583,33 @@ block unless-intro
   The directive consumer expects to bind a condition to a directive property's `myUnless` input property.
   Add the `@Input() myUnless` input property as a setter-only  (there's no need to read it).
 
+<<<<<<< a5705eb367d80adf19abf765d735b9d1189b52e6
 <<<<<<< dc4da634c40560e4eda55814676bc96a230428dc
 +makeExample('structural-directives/ts/src/app/structural-directives.component.html', 'myUnless')(format=".")
 =======
+=======
+.alert.is-critical
+  :marked
+    Ward: This first sentence threw me at first. I had to read it several times. I 
+    understand until the phrase "directive property's `myUnless` input property". I get 
+    "`myUnless` input property", since you just showed it, but I don't understand 
+    the relationship between the directive property...and the `@Input`? I don't 
+    know if I'm wording that correctly.
+
+    For the snippet below, if I were following along to build my own, I'd have only a 
+    general notion of what was being specified in it and think to mysef "ok, I'm going to 
+    trust you on this one" and scroll down to hopefully find an example of it in action. 
+    The translation below helps but thought you should know I'd feel a little in need of 
+    bravery at first glance.
+
+>>>>>>> docs(template-syntax/structural-directives): Add edits and comments on structural-directives
 +makeExample('structural-directives/ts/app/my-unless.directive.ts', 'set')(format=".")
 >>>>>>> docs(template-syntax/structural-directives): refresh both guides for style, accuracy, understanding
 :marked
   Angular calls this setter whenever the value of the condition changes.
 
   * If the condition is falsy and the view hasn't been created previously,
-  let the create the _view container_ create the _embedded view_ from the template.
+  let the _view container_ create the _embedded view_ from the template.
 
   * If the condition is truthy and the view is currently displayed, 
   clear the container which also destroys the view.
@@ -612,7 +667,7 @@ a#summary
   You learned
   * that structural directives manipulate HTML layout.
   * to use [`<ng-container>`](#ngcontainer) as a grouping element when there is no suitable host element.
-  * that the angular "de-sugars" [asterisk (\*) syntax](#asterisk) into a `<template>`
-  * how that works for the `NgIf`, `NgFor` and `NgSwitch` built-in directives
-  * about the [_microsyntax_](#microsyntax) that expands into a [`<template>`](#template)
+  * that the angular "de-sugars" [asterisk (\*) syntax](#asterisk) into a `<template>`.
+  * how that works for the `NgIf`, `NgFor` and `NgSwitch` built-in directives.
+  * about the [_microsyntax_](#microsyntax) that expands into a [`<template>`](#template).
   * to write a [custom structural directive](#unless), `myUnless`.