docs(directives): Edit directive descriptions and add examples

Author: naomiblack

lib/directive/ng_model.dart

@@ -332,9 +332,10 @@ class InputCheckbox {
 
 /**
  * Creates a two-way databinding between the `ng-model` expression
- * and the `<input>` or `<textarea>` string-based input elements.
+ * and the `<input>` or `<textarea>` string-based input elements.  `Selector: textarea[ng-model]`
+ * or `input[type=text|password|url|email|search|tel][ng-model]`
  *
-  * **Usage**
+ * **Usage**
  *
  *     <input type="text|url|password|email|search|tel" ng-model="myModel">
  *     <textarea ng-model="myModel"></textarea>
@@ -397,7 +398,7 @@ class InputTextLike {
 
 /**
  * Creates a two-way databinding between the `ng-model` expression
- * and a numeric input element. `Selector:input[type=number|range][ng-model]
+ * and a numeric input element. `Selector:input[type=number|range][ng-model]`
  *
   * **Usage**
  *
@@ -469,17 +470,17 @@ class InputNumberLike {
 }
 
 /**
- * This directive affects which IDL attribute will be used to read the value of
- * date/time related input directives. Recognized values for this directive are:
+ * Subordinate directive to [InputDateLike] that specifies the type for date/time related values.
+ * `Selector: input[type=date|time|datetime|datetime-local|month|week][ng-model][ng-bind-type]`
+ *
+ * This directive controls which IDL attribute is read and thus sets the type. This allows an app
+ * to support browsers that deviate from the HTML5 standard for date/time.
  *
- * - [DATE]: [dom.InputElement].valueAsDate will be read.
- * - [NUMBER]: [dom.InputElement].valueAsNumber will be read.
- * - [STRING]: [dom.InputElement].value will be read.
+ * Recognized values for this directive are:
  *
- * The default is [DATE]. Use other settings, e.g., when an app needs to support
- * browsers that treat date-like inputs as text (in such a case the [STRING]
- * kind would be appropriate) or, for browsers that fail to conform to the
- * HTML5 standard in their processing of date-like inputs.
+ * - [DATE]: `dom.InputElement.valueAsDate` is read. (This is the default.)
+ * - [NUMBER]: `dom.InputElement.valueAsNumber` is read.
+ * - [STRING]: `dom.InputElement.value` is read.
  */
 @Decorator(selector: 'input[type=date][ng-model][ng-bind-type]', visibility: Visibility.LOCAL)
 @Decorator(selector: 'input[type=time][ng-model][ng-bind-type]', visibility: Visibility.LOCAL)

lib/directive/ng_src_boolean.dart

@@ -1,26 +1,21 @@
 part of angular.directive;
 
 /**
- * Allows adding and removing the boolean attributes from the element.
+ * Sets boolean HTML attributes as true or false. `Selector:
+ * [ng-checked]` or `[ng-disabled]` or `[ng-multiple]` or `[ng-open]` or `[ng-readonly]` or
+ * `[ng-required]` or `[ng-selected]`
  *
- * Using `<button disabled="{{false}}">` does not work since it would result
- * in `<button disabled="false">` rather than `<button>`.
- * Browsers change behavior based on presence/absence of the attribute rather
- * its value.
+ * Since the presence of a boolean attribute on an element represents the true value,
+ * and the absence of the attribute represents the false value, `<button disabled="{{false}}">`
+ * would produce `<button disabled="false">` (which disables the button) rather than the desired
+ * result: `<button>`.
  *
- * For this reason we provide alternate `ng-`attribute directives to
- * add/remove boolean attributes such as `<button ng-disabled="{{false}}">`
- * which will result in proper removal of the attribute.
+ * Angular provides alternate `ng-`attribute directives that set elements to true or false
+ * by adding or removing boolean attributes as needed.
  *
- * The full list of supported attributes are:
+ * #Example
  *
- *  - [ng-checked]
- *  - [ng-disabled]
- *  - [ng-multiple]
- *  - [ng-open]
- *  - [ng-readonly]
- *  - [ng-required]
- *  - [ng-selected]
+ *     <button ng-disabled="isDisabled">Button</button>
  */
 @Decorator(selector: '[ng-checked]',  map: const {'ng-checked':  '=>checked'})
 @Decorator(selector: '[ng-disabled]', map: const {'ng-disabled': '=>disabled'})
@@ -82,14 +77,15 @@ class NgSource {
 }
 
 /**
- * In SVG some attributes have a specific syntax. Placing `{{interpolation}}` in
- * those attributes will break the attribute syntax, and browser will clear the
- * attribute.
+ * Provides a generic way to use `{{ }}` interpolation for attributes within validated SVG
+ * elements. `Selector: [ng-attr-*]`
  *
- * The `ng-attr-*` is a generic way to use interpolation without breaking the
- * attribute syntax validator. The `ng-attr-` part get stripped.
+ * Because the browser validates SVG syntax, using `{{interpolation}}` inside some validated
+ * `<svg>` elements causes the browser to ignore the interpolated value. The `ng-attr-*` selector
+ * inserts `{{ }}` into the element without breaking validation. (The `ng-attr-` part is stripped
+ * out during rendering.)
  *
- * @example
+ * #Example
  *     <svg>
  *       <circle ng-attr-cx="{{cx}}"></circle>
  *     </svg>