diff --git a/src/directives.js b/src/directives.js
index b9779adf17c2..f37cdde6c4d5 100644
--- a/src/directives.js
+++ b/src/directives.js
@@ -374,18 +374,28 @@ 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 href="http://www.google.com/search?q={{query}}">Google</a>
+ *   <a ng:bind-attr='{"href":"http://www.google.com/search?q={{query}}"}'>Google</a>
  * </pre>
  *
- * During compilation, the snippet gets translated to the following:
+ * This is cumbersome, so as we mentioned using double-curly markup is a prefered way of creating
+ * this binding:
  * <pre>
- *   <a ng:bind-attr='{"href":"http://www.google.com/search?q={{query}}"}'>Google</a>
+ *   <a 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
  *    the attributes to replace with expressions. Each key matches an attribute
@@ -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>