docs(scope): add $destroy event docs

1 files changed, 19 insertions, 4 deletions

diff --git a/src/service/scope.js b/src/service/scope.js
index b7ee61d6..09454bfb 100644
--- a/src/service/scope.js
+++ b/src/service/scope.js
@@ -437,6 +437,17 @@ function $RootScopeProvider(){
         this.$root.$$phase = null;
       },
 
+
+      /**
+       * @ngdoc event
+       * @name angular.module.$rootScope.Scope#$destroy
+       * @eventOf angular.module.ng.$rootScope.Scope
+       * @eventType broadcast on scope being destroyed
+       *
+       * @description
+       * Broadcasted when a scope and its children are being destroyed.
+       */
+
       /**
        * @ngdoc function
        * @name angular.module.ng.$rootScope.Scope#$destroy
@@ -445,13 +456,17 @@ function $RootScopeProvider(){
        *
        * @description
        * Remove the current scope (and all of its children) from the parent scope. Removal implies
-       * that calls to {@link angular.module.ng.$rootScope.Scope#$digest $digest()} will no longer propagate to the current
-       * scope and its children. Removal also implies that the current scope is eligible for garbage
-       * collection.
+       * that calls to {@link angular.module.ng.$rootScope.Scope#$digest $digest()} will no longer
+       * propagate to the current scope and its children. Removal also implies that the current
+       * scope is eligible for garbage collection.
        *
        * The `$destroy()` is usually used by directives such as
-       * {@link angular.module.ng.$compileProvider.directive.ng-repeat ng-repeat} for managing the unrolling of the loop.
+       * {@link angular.module.ng.$compileProvider.directive.ng-repeat ng-repeat} for managing the
+       * unrolling of the loop.
        *
+       * Just before a scope is destroyed a `$destroy` event is broadcasted on this scope.
+       * Application code can register a `$destroy` event handler that will give it chance to
+       * perform any necessary cleanup.
        */
       $destroy: function() {
         if (this.$root == this) return; // we can't remove the root node;