1 files changed, 24 insertions, 24 deletions
diff --git a/src/directives.js b/src/directives.js
index e0ac6c39..b3584a37 100644
--- a/src/directives.js
+++ b/src/directives.js
@@ -184,17 +184,19 @@ angularDirective("ng:controller", function(expression){
  * @name angular.directive.ng:bind
  *
  * @description
- * The `ng:bind` attribute tells Angular to replace the text content of the specified
- * HTML element with the value of the given expression, and to update the text
- * content whenever the expression's value changes. Usually, you would
- * just write `{{ expression }}` and let Angular compile it into
- * `<span ng:bind="expression"></span>` at bootstrap time.
+ * The `ng:bind` attribute tells Angular to replace the text content of the specified HTML element
+ * with the value of a given expression, and to update the text content when the value of that
+ * expression changes.
+ *
+ * Typically, you don't use `ng:bind` directly, but instead you use the double curly markup like
+ * `{{ expression }}` and let the Angular compiler transform it to
+ * `<span ng:bind="expression"></span>` when the template is compiled.
  *
  * @element ANY
  * @param {expression} expression {@link guide/dev_guide.expressions Expression} to evaluate.
  *
  * @example
- * Enter a name in the Live Preview text box and watch the greeting below it change instantly.
+ * Enter a name in the Live Preview text box; the greeting below the text box changes instantly.
    <doc:example>
      <doc:source>
        Enter name: <input type="text" name="name" value="Whirled"> <br>
@@ -372,42 +374,40 @@ var REMOVE_ATTRIBUTES = {
   'multiple':'multiple'
 };
 /**
- * @workInProgress
  * @ngdoc directive
  * @name angular.directive.ng:bind-attr
  *
  * @description
- * The `ng:bind-attr` attribute specifies that
- * {@link guide/dev_guide.templates.databinding databindings}  should be created between element
- * attributes and given expressions. Unlike `ng:bind` the `ng:bind-attr` contains a JSON key value
- * pairs representing which attributes need to be mapped to which
- * {@link guide/dev_guide.expressions expressions}.
- *
- * You don't usually write the `ng:bind-attr` in the HTML since embedding
- * <tt ng:non-bindable>{{expression}}</tt> into the attribute directly as the attribute value is
- * preferred. The attributes get translated into `<span ng:bind-attr="{attr:expression}"/>` at
- * compile time.
- *
- * This HTML snippet is preferred way of working with `ng:bind-attr`
+ * The `ng:bind-attr` attribute specifies that a
+ * {@link guide/dev_guide.templates.databinding databinding}  should be created between a particular
+ * element attribute and a given expression. Unlike `ng:bind`, the `ng:bind-attr` contains one or
+ * more JSON key value pairs; each pair specifies an attribute and the
+ * {@link guide/dev_guide.expressions expression} to which it will be mapped.
+ *
+ * Instead of writing `ng:bind-attr` statements in your HTML, you can use double-curly markup to
+ * specify an <tt ng:non-bindable>{{expression}}</tt> for the value of an attribute.
+ * At compile time, the attribute is translated into an `<span ng:bind-attr="{attr:expression}"/>`
+ *
+ * The following HTML snippet shows how to specify `ng:bind-attr`:
  * <pre>
  *   <a href="http://www.google.com/search?q={{query}}">Google</a>
  * </pre>
  *
- * The above gets translated to bellow during bootstrap time.
+ * During compilation, the snippet gets translated to the following:
  * <pre>
  *   <a ng:bind-attr='{"href":"http://www.google.com/search?q={{query}}"}'>Google</a>
  * </pre>
  *
  * @element ANY
- * @param {string} attribute_json a JSON key-value pairs representing
- *    the attributes to replace. Each key matches the attribute
+ * @param {string} attribute_json one or more JSON key-value pairs representing
+ *    the attributes to replace with expressions. Each key matches an attribute
  *    which needs to be replaced. Each value is a text template of
- *    the attribute with embedded
+ *    the attribute with the embedded
  *    <tt ng:non-bindable>{{expression}}</tt>s. Any number of
  *    key-value pairs can be specified.
  *
  * @example
- * Try it here: enter text in text box and click Google.
+ * Enter a search string in the Live Preview text box and then click "Google". The search executes instantly.
    <doc:example>
      <doc:source>
       Google for: