docs for angular.element

1 files changed, 50 insertions, 0 deletions

diff --git a/src/Angular.js b/src/Angular.js
index 60aa0259..9dddaded 100644
--- a/src/Angular.js
+++ b/src/Angular.js
@@ -82,6 +82,52 @@ var _undefined        = undefined,
     _                 = window['_'],
     /** holds major version number for IE or NaN for real browsers */
     msie              = parseInt((/msie (\d+)/.exec(lowercase(navigator.userAgent)) || [])[1], 10),
+
+    /**
+     * @workInProgress
+     * @ngdoc function
+     * @name angular.element
+     * @function
+     *
+     * @description
+     * Wraps a raw DOM element or HTML string as [jQuery](http://jquery.com) element.
+     * `angular.element` is either an alias for [jQuery](http://api.jquery.com/jQuery/) function if
+     * jQuery is loaded or a function that wraps the element or string in angular's jQuery lite
+     * implementation.
+     *
+     * Real jQuery always takes precedence if it was loaded before angular.
+     *
+     * Angular's jQuery lite implementation is a tiny API-compatible subset of jQuery which allows
+     * angular to manipulate DOM.  The functions implemented are usually just the basic versions of
+     * them and might not support arguments and invocation styles.
+     *
+     * NOTE: All element references in angular are always wrapped with jQuery (lite) and are never
+     * raw DOM references.
+     *
+     * Angular's jQuery lite implements these functions:
+     *
+     * - [addClass()](http://api.jquery.com/addClass/)
+     * - [after()](http://api.jquery.com/after/)
+     * - [append()](http://api.jquery.com/append/)
+     * - [attr()](http://api.jquery.com/attr/)
+     * - [bind()](http://api.jquery.com/bind/)
+     * - [children()](http://api.jquery.com/children/)
+     * - [clone()](http://api.jquery.com/clone/)
+     * - [css()](http://api.jquery.com/css/)
+     * - [data()](http://api.jquery.com/data/)
+     * - [hasClass()](http://api.jquery.com/hasClass/)
+     * - [parent()](http://api.jquery.com/parent/)
+     * - [remove()](http://api.jquery.com/remove/)
+     * - [removeAttr()](http://api.jquery.com/removeAttr/)
+     * - [removeClass()](http://api.jquery.com/removeClass/)
+     * - [removeData()](http://api.jquery.com/removeData/)
+     * - [replaceWith()](http://api.jquery.com/replaceWith/)
+     * - [text()](http://api.jquery.com/text/)
+     * - [trigger()](http://api.jquery.com/trigger/)
+     *
+     * @param {string|DOMElement} element HTML string or DOMElement to be wrapped into jQuery.
+     * @returns {Object} jQuery object.
+     */
     jqLite            = jQuery || jqLiteWrap,
     slice             = Array.prototype.slice,
     push              = Array.prototype.push,
@@ -599,6 +645,7 @@ function inherit(parent, extra) {
  */
 function noop() {}
 
+
 /**
  * @workInProgress
  * @ngdoc function
@@ -616,8 +663,11 @@ function noop() {}
    </pre>
  */
 function identity($) {return $;}
+
+
 function valueFn(value) {return function(){ return value; };}
 
+
 function extensionMap(angular, name, transform) {
   var extPoint;
   return angular[name] || (extPoint = angular[name] = function (name, fn, prop){