docs(structural-directive): answer K's questions for W

Author: wardbell

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

@@ -27,15 +27,6 @@ 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,14 +40,16 @@ a#definition
   The directive then does whatever it's supposed to do with that host element and its descendents.
 
   Structural directives are easy to recognize. 
-  An asterisk (\*) precedes the directive selector name which is set to a string.
+  An asterisk (\*) precedes the directive attribute name as in this example.
 +makeExample('structural-directives/ts/app/app.component.html', 'ngif')(format=".")
 :marked
-  No brackets. No parentheses. Just a string, which is either a [template expression](template-syntax.html#template-expressions)
-  or a [microsyntax](#microsyntax).
+  No brackets. No parentheses. Just `*ngIf` set to a string.
 
-  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.
+  You'll learn in this guide that the [asterisk (\*) is a convenience notation](#asterisk)
+  and the string is a [_microsyntax_](#microsyntax) rather than the usual [template expression](template-syntax.html#template-expressions).
+  Angular "de-sugars" this notation into a marked-up `<template>` that surrounds 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 
@@ -68,6 +61,20 @@ a#definition
   This guide won't repeat how to _use_ them. But it does explain _how they work_
   and how to [write your own](#unless) structural directive.
 
+.callout.is-helpful
+  header Directive spelling
+  :marked
+     Throughout this guide, you'll see a directive spelled in both _UpperCamelCase_ and _lowerCamelCase_.
+     Already you've seen `NgIf` and `ngIf`.
+     There's a reason. `NgIf` refers to the directive _class_; 
+     `ngIf` refers to the directive's _attribute name_. 
+     
+     A directive _class_ is spelled in _UpperCamelCase_ (`NgIf`).
+     A directive's _attribute name_ is spelled in _lowerCamelCase_ (`ngIf`).
+     The guide refers to the directive _class_ when talking about its properties and what the directive does.
+     The guide refers to the _attribute name_ when describing how
+     you apply the directive to an element in the HTML template.
+
 .l-sub-section
   :marked
     There are two other kinds of Angular directives, described extensively elsewhere: (1)&nbsp;components and (2)&nbsp;attribute directives.
@@ -83,7 +90,6 @@ a#definition
     You can apply many _attribute_ directives to one host element.
     You can [only apply one](#one-per-element) _structural_ directive to a host element.
 
-
 a#ngIf
 .l-main-section
 :marked
@@ -141,8 +147,8 @@ figure.image-display
   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
-  about the consequences of adding and removing elements and of creating and destroying components.
+  Before applying a structural directive, you might want to pause for a moment 
+  to consider the consequences of adding and removing elements and of creating and destroying components.
 
 a#ngcontainer
 a#ng-container
@@ -280,12 +286,12 @@ 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 application of `NgFor`, written all three ways:
 +makeExample('structural-directives/ts/app/app.component.html', 'inside-ngfor')(format=".")
 
 :marked
   This is manifestly more complicated than `ngIf` and rightly so.
-  The `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). 
@@ -304,32 +310,30 @@ a#microsyntax
 
   * The `let` keyword declares a [_template input variable_](#template-input-variable) 
   that you reference within the template. The input variables in this example are `hero`, `i`, and `odd`.
-  The parser translates `let hero`, `let i`, and `let odd` into the declaration tokens, 
+  The parser translates `let hero`, `let i`, and `let odd` into variables named, 
   `let-hero`, `let-i`, and `let-odd`.
 
-  * The `of` and `trackby` translate to the `ngForOf` and `ngForTrackBy` _input properties_ of the `NgFor` directive. 
-  The parser creates these directive property names by title-casing the name-fragment (`of` -> `Of`, `trackBy` -> `TrackBy`) and 
-  and prefixing it with the directive key (`ngFor`).
+  * The microsyntax parser takes `of` and `trackby`, title-cases them (`of` -> `Of`, `trackBy` -> `TrackBy`), 
+  and prefixes them with the directive's attribute name (`ngFor`), yielding the names `ngForOf` and `ngForTrackBy`.
+  Those are the names of two `NgFor` _input properties_ .
+  That's how the directive learns that the list is `heroes` and the track-by function is `trackById`.
 
-  * The one unassigned _let_ variable (`hero`) is tied to the directive _context's_ `$implicit` property.
-  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.
+  * As the `NgFor` directive loops through the list, it sets and resets properties of its own _context_ object.
+  These properties include `index` and `odd` and a special property named `$implicit`.
 
-.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`.
+  * The `let-i` and `let-odd` variables were defined as `let i=index` and `let odd=odd`.
+  Angular sets them to the current value of the context's `index` and `odd` properties.
+
+  * The context property for `let-hero` wasn't specified. 
+  It's intended source is implicit. 
+  Angular sets `let-hero` to the value of the context's `$implicit` property
+  which `NgFor` has initialized with the hero for the current iteration.
 
-  You can leverage the microsyntax in your own structural directive, should you decide to write one as
-  complex as `NgFor`.
-  Studying the source code for `NgFor` is the best way to learn.
+  * The [API guide](../api/common/index/NgFor-directive.html "API: NgFor") 
+  describes additional `NgFor` directive properties and context properties.
+
+  These microsyntax mechanisms are available to you when you write your own structural directives.
+  Studying the source code for `NgIf` and `NgFor` is a great way to learn more.
 
 
 a#template-input-variable
@@ -384,26 +388,30 @@ a#ngswitch
 +makeExample('structural-directives/ts/app/app.component.html', 'ngswitch')(format=".")
 
 :marked
+  The switch value assigned to `NgSwitch` (`hero.emotion`) determines which
+  (if any) of the switch cases are displayed.
+  
   `NgSwitch` itself is not a structural directive. 
-  It's an _attribute_ directive that controls the behavior of the `NgSwitchCase` and `NgSwitchDefault`.
+  It's an _attribute_ directive that controls the behavior of the other two switch directives.
   That's why you write `[ngSwitch]`, never `*ngSwitch`.
 
-  `NgSwitchCase` and `NgSwitchDefault` are structural directives and are written with the asterisk (\*) prefix. 
-  `NgSwitchCase` includes its host element when its value matches the `NgSwitch` value.
-  `NgSwitchDefault` includes its host element when no `NgSwitchCase` does.
+  `NgSwitchCase` and `NgSwitchDefault` _are_ structural directives. 
+  You attach them to elements using the asterisk (\*) prefix notation. 
+  An `NgSwitchCase` displays its host element when its value matches the switch value.
+  The `NgSwitchDefault` displays its host element when no sibling `NgSwitchCase` matches the switch value.
 
-.alert.is-critical
+.l-sub-section
   :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?
+    The element to which you apply a directive is its _host_ element. 
+    The `<happy-hero>` is the host element for the happy `*ngSwitchCase`.
+    The `<unknown-hero>` is the host element for the `*ngSwitchDefault`.
 
 :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=".")
 :marked
-  The `<template>` element form is verbose.
+  That, in turn, can be "de-sugared" into the `<template>` element form.
 +makeExample('structural-directives/ts/app/app.component.html', 'ngswitch-template')(format=".")
 
 a#prefer-asterisk
@@ -470,20 +478,15 @@ block unless-intro
 +makeExample('structural-directives/ts/app/my-unless.directive.ts', 'skeleton', 'my-unless.directive.ts (skeleton)')(format=".")
 
 :marked
-  The directive's _selector_ is typically the directive's **key** in square brackets.`[myUnless]`.
+  The directive's _selector_ is typically the directive's **attribute name** in square brackets.`[myUnless]`.
   The brackets define a CSS
   <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors" target="_blank" title="MDN: Attribute selectors">attribute selector</a>.
 
-  The directive _key_ should be spelled in _lowerCamelCase_ and begin with a prefix.
+  The directive _attribute name_ should be spelled in _lowerCamelCase_ and begin with a prefix.
   Don't use `ng`. That prefix belongs to Angular.
   Pick something short that fits you or your company.
   In this example, the prefix is `my`.
 
-.alert.is-critical
-  :marked
-    Ward: Why is this called a *key* when it looks like the value in a 
-    key value pair?^^
-
 :marked
   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.
@@ -506,33 +509,27 @@ block unless-intro
 +makeExample('structural-directives/ts/app/my-unless.directive.ts', 'ctor')(format=".")
 
 :marked
-  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).
+  ### The _myUnless_ property
 
-.alert.is-critical
+  The directive consumer expects to bind a true/false condition to `[myUnless]`.
+  That means the directive needs a `myUnless` property, decorated with `@Input` 
+.l-sub-section
   :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.
+    Read about `@Input` in the [_Template Syntax_](template-syntax.html#inputs-outputs) guide.
 
 +makeExample('structural-directives/ts/app/my-unless.directive.ts', 'set')(format=".")
 :marked
-  Angular calls this setter whenever the value of the condition changes.
+  Angular sets the  `myUnless` property whenever the value of the condition changes.
+  Because the `myUnless` property does work, it needs a setter.
 
   * If the condition is falsy and the view hasn't been created previously,
-  let the _view container_ create the _embedded view_ from the template.
+  tell the _view container_ to 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.
 
+  Nobody reads the `myUnless` property so it doesn't need a getter.
+  
   The completed directive code looks like this:
 
 +makeExample('structural-directives/ts/app/my-unless.directive.ts', 'no-docs', 'my-unless.directive.ts')