docs(ng:bind-attr): improve examples

src/directives.js

@@ -374,17 +374,27 @@ angularDirective("ng:bind-template", function(expression, element){
  *
  * 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}"/>`
+ * At compile time, the attribute is translated into an
+ * `<span ng:bind-attr="{attr:expression}"></span>`.
  *
  * The following HTML snippet shows how to specify `ng:bind-attr`:
  * <pre>
+ *   <a ng:bind-attr='{"href":"http://www.google.com/search?q={{query}}"}'>Google</a>
+ * </pre>
+ *
+ * This is cumbersome, so as we mentioned using double-curly markup is a prefered way of creating
+ * this binding:
+ * <pre>
  *   <a href="http://www.google.com/search?q={{query}}">Google</a>
  * </pre>
  *
- * 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>
+ * During compilation, the template with attribute markup gets translated to the ng:bind-attr form
+ * mentioned above.
+ *
+ * _Note_: You might want to consider using {@link angular.directive.ng:href ng:href} instead of
+ * `href` if the binding is present in the main application template (`index.html`) and you want to
+ * make sure that a user is not capable of clicking on raw/uncompiled link.
+ *
  *
  * @element ANY
  * @param {string} attribute_json one or more JSON key-value pairs representing
@@ -406,7 +416,11 @@ angularDirective("ng:bind-template", function(expression, element){
        <div ng:controller="Ctrl">
         Google for:
         <input type="text" ng:model="query"/>
+        <a ng:bind-attr='{"href":"http://www.google.com/search?q={{query}}"}'>
+          Google
+        </a> (ng:bind-attr) |
         <a href="http://www.google.com/search?q={{query}}">Google</a>
+        (curly binding in attribute val)
        </div>
      </doc:source>
      <doc:scenario>