fixup: better examples

Author: Narretz

src/ng/compile.js

@@ -952,39 +952,49 @@
  * not an intended use case and can lead to misbehaving directives, performance issues, and memory
  * leaks.
  * A common scenario where this happens is a directive that calls `$compile` in a directive link
- * function on the directive element:
+ * function on the directive element. In the following example, a directive adds a mouseover behavior
+ * to a button with `ngClick` on it:
  *
  * ```
-  angular.module('app').directive('addInput', function($compile) {
+  angular.module('app').directive('addMouseover', function($compile) {
     return {
       link: function(scope, element, attrs) {
-        var newEl = angular.element('<input ng-model="$ctrl.value">');
-        attrs.$set('addInput', null) // To stop infinite compile loop
+        var newEl = angular.element('<span ng-show="showHint"> My Hint</span>');
+        element.on('mouseenter mouseout', function() {
+          scope.$apply('showHint = !showHint');
+        });
+
+        attrs.$set('addMouseover', null); // To stop infinite compile loop
         element.append(newEl);
         $compile(element)(scope); // Double compilation
       }
     }
   })
   ```
- * At first glance, it looks like removing the original `addInput` attribute is all there is needed
+ * At first glance, it looks like removing the original `addMouseover` attribute is all there is needed
  * to make this example work.
  * However, if the directive element or its children have other directives attached, they will be compiled and
  * linked again, because the compiler doesn't keep track of which directives have been assigned to which
  * elements.
  *
- * This can cause unpredictable behavior, e.g. `ngModel` $formatters and $parsers will be
- * attached again to the ngModelController. It can also degrade performance, as
- * watchers for text interpolation are added twice to the scope.
+ * This can cause unpredictable behavior, e.g. `ngClick` or other event handlers will be attached
+ * again. It can also degrade performance, as watchers for text interpolation are added twice to the scope.
+ *
+ * Double compilation should therefore be avoided. In the above example, only the new element should
+ * be compiled:
  *
- * Double compilation should therefore avoided. In the above example, the better way is to only
- * compile the new element:
  * ```
-  angular.module('app').directive('addInput', function($compile) {
+  angular.module('app').directive('addMouseover', function($compile) {
     return {
       link: function(scope, element, attrs) {
-        var newEl = angular.element('<input ng-model="$ctrl.value">');
-        $compile(newEl)(scope); // Only compile the new element
+        var newEl = angular.element('<span ng-show="showHint"> My Hint</span>');
+        element.on('mouseenter mouseout', function() {
+          scope.$apply('showHint = !showHint');
+        });
+
+        attrs.$set('addMouseover', null);
         element.append(newEl);
+        $compile(newEl)(scope); // Only compile the new element
       }
     }
   })
@@ -1000,7 +1010,7 @@
   angular.module('app').directive('addOptions', function($compile) {
     return {
       link: function(scope, element, attrs) {
-        attrs.$set('addInput', null) // To stop infinite compile loop
+        attrs.$set('addOptions', null) // To stop infinite compile loop
         attrs.$set('ngModelOptions', '{debounce: 1000}');
         $compile(element)(scope); // Double compilation
       }
@@ -1010,15 +1020,15 @@
  *
  * In that case, it is necessary to intercept the *initial* compilation of the element:
  *
- * 1. give your directive the `terminal` property and a higher priority than directives
+ * 1. Give your directive the `terminal` property and a higher priority than directives
  * that should not be compiled twice. In the example, the compiler will only compile directives
  * which have a priority of 100 or higher.
- * 2. inside this directive's compile function, remove the original directive attribute from the element,
+ * 2. Inside this directive's compile function, remove the original directive attribute from the element,
  * and add any other directive attributes. Removing the attribute is necessary, because otherwise the
  * compilation would result in an infinite loop.
- * 3. compile the element but restrict the maximum priority, so that any already compiled directives
+ * 3. Compile the element but restrict the maximum priority, so that any already compiled directives
  * are not compiled twice.
- * 4. in the link function, link the compiled element with the element's scope
+ * 4. In the link function, link the compiled element with the element's scope
  *
  * ```
   angular.module('app').directive('addOptions', function($compile) {
@@ -1027,9 +1037,10 @@
       terminal: true,
       template: '<input ng-model="$ctrl.value">',
       compile: function(templateElement, templateAttributes) {
-        templateAttributes.$set('addOptions', null);
         templateAttributes.$set('ngModelOptions', '{debounce: 1000}');
 
+        // The third argument is the max priority. Only directives with priority < 100 will be compiled,
+        // therefore we don't need to remove the attribute
         var compiled = $compile(templateElement, null, 100);
 
         return function linkFn(scope) {