From 52123ae85bc131d070ce9e7102b3c5fbbb872fba Mon Sep 17 00:00:00 2001
From: Pete Bacon Darwin
Date: Thu, 18 Jul 2013 19:39:18 +0100
Subject: docs(jqLite): document "$destroy" event

---
 src/jqLite.js       | 11 +++++++++--
 src/ng/rootScope.js |  6 ++++++
 2 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/src/jqLite.js b/src/jqLite.js
index e1231b61..072557ba 100644
--- a/src/jqLite.js
+++ b/src/jqLite.js
@@ -26,7 +26,8 @@
  * Note: All element references in Angular are always wrapped with jQuery or jqLite; they are never
  * raw DOM references.
  *
- * ## Angular's jQuery lite provides the following methods:
+ * ## Angular's jqLite
+ * Angular's lite version of jQuery provides only the following jQuery methods:
  *
  * - [addClass()](http://api.jquery.com/addClass/)
  * - [after()](http://api.jquery.com/after/)
@@ -61,8 +62,14 @@
  * - [val()](http://api.jquery.com/val/)
  * - [wrap()](http://api.jquery.com/wrap/)
  *
- * ## In addition to the above, Angular provides additional methods to both jQuery and jQuery lite:
+ * ## jQuery/jqLite Extras
+ * Angular also provides the following additional methods and events to both jQuery and jqLite:
  *
+ * ### Events
+ * - `$destroy` - AngularJS intercepts all jqLite/jQuery's DOM destruction apis and fires this event
+ *    on all DOM nodes being removed.  This can be used to clean up and 3rd party bindings to the DOM
+ *    element before it is removed.
+ * ### Methods
  * - `controller(name)` - retrieves the controller of the current element or its parent. By default
  *   retrieves controller associated with the `ngController` directive. If `name` is provided as
  *   camelCase directive name, then the controller for this directive will be retrieved (e.g.
diff --git a/src/ng/rootScope.js b/src/ng/rootScope.js
index f95d1c91..06609862 100644
--- a/src/ng/rootScope.js
+++ b/src/ng/rootScope.js
@@ -575,6 +575,9 @@ function $RootScopeProvider(){
        *
        * @description
        * Broadcasted when a scope and its children are being destroyed.
+       * 
+       * Note that, in AngularJS, there is also a `$destroy` jQuery event, which can be used to
+       * clean up DOM bindings before an element is removed from the DOM.
        */
 
       /**
@@ -596,6 +599,9 @@ function $RootScopeProvider(){
        * 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.
+       * 
+       * Note that, in AngularJS, there is also a `$destroy` jQuery event, which can be used to
+       * clean up DOM bindings before an element is removed from the DOM.
        */
       $destroy: function() {
         // we can't destroy the root scope or a scope that has been already destroyed
-- 
cgit v1.2.3