docs(ngIf): formatting, clarity

src/ng/directive/ngIf.js

@@ -6,32 +6,31 @@
  * @restrict A
  *
  * @description
- * The `ngIf` directive removes and recreates a portion of the DOM tree (HTML)
+ * The `ngIf` directive removes or recreates a portion of the DOM tree based on an
- * conditionally based on **"falsy"** and **"truthy"** values, respectively, evaluated within
+ * {expression}. If the expression assigned to `ngIf` evaluates to a false
- * an {expression}. In other words, if the expression assigned to **ngIf evaluates to a false
+ * value then the element is removed from the DOM, otherwise a clone of the
- * value** then **the element is removed from the DOM** and **if true** then **a clone of the
+ * element is reinserted into the DOM.
- * element is reinserted into the DOM**.
  *
  * `ngIf` differs from `ngShow` and `ngHide` in that `ngIf` completely removes and recreates the
  * element in the DOM rather than changing its visibility via the `display` css property.  A common
  * case when this difference is significant is when using css selectors that rely on an element's
- * position within the DOM (HTML), such as the `:first-child` or `:last-child` pseudo-classes.
+ * position within the DOM, such as the `:first-child` or `:last-child` pseudo-classes.
  *
- * Note that **when an element is removed using ngIf its scope is destroyed** and **a new scope
+ * Note that when an element is removed using `ngIf` its scope is destroyed and a new scope
- * is created when the element is restored**.  The scope created within `ngIf` inherits from 
+ * is created when the element is restored.  The scope created within `ngIf` inherits from 
  * its parent scope using
  * {@link https://github.com/angular/angular.js/wiki/The-Nuances-of-Scope-Prototypal-Inheritance prototypal inheritance}.
  * An important implication of this is if `ngModel` is used within `ngIf` to bind to
  * a javascript primitive defined in the parent scope. In this case any modifications made to the
  * variable within the child scope will override (hide) the value in the parent scope.
  *
- * Also, `ngIf` recreates elements using their compiled state. An example scenario of this behavior
+ * Also, `ngIf` recreates elements using their compiled state. An example of this behavior
  * is if an element's class attribute is directly modified after it's compiled, using something like 
  * jQuery's `.addClass()` method, and the element is later removed. When `ngIf` recreates the element
  * the added class will be lost because the original compiled state is used to regenerate the element.
  *
- * Additionally, you can provide animations via the ngAnimate module to animate the **enter**
+ * Additionally, you can provide animations via the `ngAnimate` module to animate the `enter`
- * and **leave** effects.
+ * and `leave` effects.
  *
  * @animations
  * enter - happens just after the ngIf contents change and a new DOM element is created and injected into the ngIf container
@@ -40,7 +39,8 @@
  * @element ANY
  * @scope
  * @param {expression} ngIf If the {@link guide/expression expression} is falsy then
- *     the element is removed from the DOM tree (HTML).
+ *     the element is removed from the DOM tree. If it is truthy a copy of the compiled
+ *     eleent is added to the DOM tree.
  *
  * @example
   <example animations="true">