X-Git-Url: http://git.asbjorn.biz/?a=blobdiff_plain;f=jquery%2Fjquery.js;h=4f01825d6b45654e04856a096daba9e47024f657;hb=8192bd8e914822b54abcc245fe8013cd6c78e6cb;hp=86a706005b24b0a0465aec76699dcfc3e35b8b02;hpb=df9c37ec852f8c873e226cd0ae190f969e0edc17;p=jquery.git

diff --git a/jquery/jquery.js b/jquery/jquery.js
index 86a7060..4f01825 100644
--- a/jquery/jquery.js
+++ b/jquery/jquery.js
@@ -457,9 +457,9 @@ jQuery.fn = jQuery.prototype = {
 	},
 	
 	/**
-	 * End all 'destructive' operations, reverting the list of matched elements.
-	 * After an end operation, the list of matched elements will revert to the last
-	 * state of matched elements.
+	 * End the most recent 'destructive' operation, reverting the list of matched elements
+	 * back to its previous state. After an end operation, the list of matched elements will 
+	 * revert to the last state of matched elements.
 	 *
 	 * @example $("p").find("span").end();
 	 * @before <p><span>Hello</span>, how are you?</p>
@@ -472,12 +472,62 @@ jQuery.fn = jQuery.prototype = {
 		return this.get( this.stack.pop() );
 	},
 	
+	/**
+	 * Searches for all elements that match the specified expression.
+	 * This method is the optimal way of finding additional descendant
+	 * elements with which to process.
+	 *
+	 * All searching is done using a jQuery expression. The expression can be 
+	 * written using CSS 1-3 Selector syntax, or basic XPath.
+	 *
+	 * @example $("p").find("span");
+	 * @before <p><span>Hello</span>, how are you?</p>
+	 * @result $("p").find("span") == [ <span>Hello</span> ]
+	 *
+	 * @name find
+	 * @type jQuery
+	 * @param String expr An expression to search with.
+	 */
 	find: function(t) {
 		return this.pushStack( jQuery.map( this, function(a){
 			return jQuery.find(t,a);
 		}), arguments );
 	},
 	
+	/**
+	 * Removes all elements from the set of matched elements that do not 
+	 * match the specified expression. This method is used to narrow down
+	 * the results of a search.
+	 *
+	 * All searching is done using a jQuery expression. The expression
+	 * can be written using CSS 1-3 Selector syntax, or basic XPath.
+	 * 
+	 * @example $("p").filter(".selected")
+	 * @before <p class="selected">Hello</p><p>How are you?</p>
+	 * @result $("p").filter(".selected") == [ <p class="selected">Hello</p> ]
+	 *
+	 * @name filter
+	 * @type jQuery
+	 * @param String expr An expression to search with.
+	 */
+
+	 /**
+	  * Removes all elements from the set of matched elements that do not
+	  * match at least one of the expressions passed to the function. This 
+	  * method is used when you want to filter the set of matched elements 
+	  * through more than one expression.
+	  *
+	  * Elements will be retained in the jQuery object if they match at
+	  * least one of the expressions passed.
+	  *
+	  * @example $("p").filter([".selected", ":first"])
+	  * @before <p>Hello</p><p>Hello Again</p><p class="selected">And Again</p>
+	  * @result $("p").filter([".selected", ":first"]) == [ <p>Hello</p>, <p class="selected">And Again</p> ]
+	  *
+	  * @name filter
+	  * @type jQuery
+	  * @param Array<String> exprs A set of expressions to evaluate against
+	  */
 	filter: function(t) {
 		return t.constructor == Array ?
 			// Multi Filtering
@@ -490,12 +540,76 @@ jQuery.fn = jQuery.prototype = {
 			this.pushStack( jQuery.filter(t,this).r, arguments );
 	},
 	
+	/**
+	 * Removes the specified Element from the set of matched elements. This
+	 * method is used to remove a single Element from a jQuery object.
+	 *
+	 * @example $("p").not( document.getElementById("selected") )
+	 * @before <p>Hello</p><p id="selected">Hello Again</p>
+	 * @result [ <p>Hello</p> ]
+	 *
+	 * @name not
+	 * @type jQuery
+	 * @param Element el An element to remove from the set
+	 */
+
+	/**
+	 * Removes elements matching the specified expression from the set
+	 * of matched elements. This method is used to remove one or more
+	 * elements from a jQuery object.
+	 * 
+	 * @example $("p").not("#selected")
+	 * @before <p>Hello</p><p id="selected">Hello Again</p>
+	 * @result [ <p>Hello</p> ]
+	 *
+	 * @name not
+	 * @type jQuery
+	 * @param String expr An expression with which to remove matching elements
+	 */
 	not: function(t) {
 		return this.pushStack( t.constructor == String ?
 			jQuery.filter(t,this,false).r :
 			jQuery.grep(this,function(a){ return a != t; }), arguments );
 	},
-	
+
+	/**
+	 * Adds the elements matched by the expression to the jQuery object. This
+	 * can be used to concatenate the result sets of two expressions.
+	 *
+	 * @example $("p").add("span")
+	 * @before <p>Hello</p><p><span>Hello Again</span></p>
+	 * @result [ <p>Hello</p>, <span>Hello Again</span> ]
+	 *
+	 * @name add
+	 * @type jQuery
+	 * @param String expr An expression whose matched elements are added
+	 */
+
+	/**
+	 * Adds each of the Elements in the array to the set of matched elements.
+	 * This is used to add a set of Elements to a jQuery object.
+	 *
+	 * @example $("p").add([document.getElementById("a"), document.getElementById("b")])
+	 * @before <p>Hello</p><p><span id="a">Hello Again</span><span id="b">And Again</span></p>
+	 * @result [ <p>Hello</p>, <span id="a">Hello Again</span>, <span id="b">And Again</span> ]
+	 *
+	 * @name add
+	 * @type jQuery
+	 * @param Array<Element> els An array of Elements to add
+	 */
+
+	 /**
+	  * Adds a single Element to the set of matched elements. This is used to
+	  * add a single Element to a jQuery object.
+	  *
+	  * @example $("p").add( document.getElementById("a") )
+	  * @before <p>Hello</p><p><span id="a">Hello Again</span></p>
+	  * @result [ <p>Hello</p>, <span id="a">Hello Again</span> ]
+	  *
+	  * @name add
+	  * @type jQuery
+	  * @param Element el An Element to add
+	  */
 	add: function(t) {
 		return this.pushStack( jQuery.merge( this, t.constructor == String ?
 			jQuery.find(t) : t.constructor == Array ? t : [t] ), arguments );
@@ -515,7 +629,7 @@ jQuery.fn = jQuery.prototype = {
 	},
 	
 	/**
-	 * :-P
+	 * 
 	 *
 	 * @private
 	 * @name domManip
@@ -575,7 +689,11 @@ jQuery.fn = jQuery.prototype = {
 		return this;
 	},
 	
-	extend: function(obj,prop) {
		if ( !prop ) {
			prop = obj;
			obj = this;
		}
	
		for ( var i in prop )
			obj[i] = prop[i];
	
		return obj;
	}
+	extend: function(obj,prop) {
+		if ( !prop ) { prop = obj; obj = this; }
+		for ( var i in prop ) obj[i] = prop[i];
+		return obj;
+	}
 };
 
 jQuery.extend = jQuery.fn.extend;
@@ -595,11 +713,147 @@ new function() {
 	jQuery.boxModel = !jQuery.browser.msie || document.compatMode == "CSS1Compat";
 
 	var axis = {
+		/**
+		 * Get a set of elements containing the unique parents of the matched
+		 * set of elements.
+		 *
+		 * @example $("p").parent()
+		 * @before <div><p>Hello</p><p>Hello</p></div>
+		 * @result [ <div><p>Hello</p><p>Hello</p></div> ]
+		 *
+		 * @name parent
+		 * @type jQuery
+		 */
+
+		/**
+		 * Get a set of elements containing the unique parents of the matched
+		 * set of elements, and filtered by an expression.
+		 *
+		 * @example $("p").parent(".selected")
+		 * @before <div><p>Hello</p></div><div class="selected"><p>Hello Again</p></div>
+		 * @result [ <div class="selected"><p>Hello Again</p></div> ]
+		 *
+		 * @name parent
+		 * @type jQuery
+		 * @param String expr An expression to filter the parents with
+		 */
 		parent: "a.parentNode",
-		parents: jQuery.parents,
+
+		/**
+		 * Get a set of elements containing the unique ancestors of the matched
+		 * set of elements.
+		 *
+		 * @example $("span").ancestors()
+		 * @before <html><body><div><p><span>Hello</span></p><span>Hello Again</span></div></body></html>
+		 * @result [ <body>...</body>, <div>...</div>, <p><span>Hello</span></p> ] 
+		 *
+		 * @name ancestors
+		 * @type jQuery
+		 */
+
+		/**
+		 * Get a set of elements containing the unique ancestors of the matched
+		 * set of elements, and filtered by an expression.
+		 *
+		 * @example $("span").ancestors("p")
+		 * @before <html><body><div><p><span>Hello</span></p><span>Hello Again</span></div></body></html>
+		 * @result [ <p><span>Hello</span></p> ] 
+		 *
+		 * @name ancestors
+		 * @type jQuery
+		 * @param String expr An expression to filter the ancestors with
+		 */
 		ancestors: jQuery.parents,
+		
+		/**
+		 * A synonym for ancestors
+		 */
+		parents: jQuery.parents,
+
+		/**
+		 * Get a set of elements containing the unique next siblings of each of the 
+		 * matched set of elements.
+		 * 
+		 * It only returns the very next sibling, not all next siblings.
+		 *
+		 * @example $("p").next()
+		 * @before <p>Hello</p><p>Hello Again</p><div><span>And Again</span></div>
+		 * @result [ <p>Hello Again</p>, <div><span>And Again</span></div> ]
+		 *
+		 * @name next
+		 * @type jQuery
+		 */
+
+		/**
+		 * Get a set of elements containing the unique next siblings of each of the 
+		 * matched set of elements, and filtered by an expression.
+		 * 
+		 * It only returns the very next sibling, not all next siblings.
+		 *
+		 * @example $("p").next(".selected")
+		 * @before <p>Hello</p><p class="selected">Hello Again</p><div><span>And Again</span></div>
+		 * @result [ <p class="selected">Hello Again</p> ]
+		 *
+		 * @name next
+		 * @type jQuery
+		 * @param String expr An expression to filter the next Elements with
+		 */
 		next: "a.nextSibling",
+
+		/**
+		 * Get a set of elements containing the unique previous siblings of each of the 
+		 * matched set of elements.
+		 * 
+		 * It only returns the immediately previous sibling, not all previous siblings.
+		 *
+		 * @example $("p").previous()
+		 * @before <p>Hello</p><div><span>Hello Again</span></div><p>And Again</p>
+		 * @result [ <div><span>Hello Again</span></div> ]
+		 *
+		 * @name prev
+		 * @type jQuery
+		 */
+
+		/**
+		 * Get a set of elements containing the unique previous siblings of each of the 
+		 * matched set of elements, and filtered by an expression.
+		 * 
+		 * It only returns the immediately previous sibling, not all previous siblings.
+		 *
+		 * @example $("p").previous("selected")
+		 * @before <div><span>Hello</span></div><p class="selected">Hello Again</p><p>And Again</p>
+		 * @result [ <div><span>Hello</span></div> ]
+		 *
+		 * @name prev
+		 * @type jQuery
+		 * @param String expr An expression to filter the previous Elements with
+		 */
 		prev: "a.previousSibling",
+
+		/**
+		 * Get a set of elements containing all of the unique siblings of each of the 
+		 * matched set of elements.
+		 * 
+		 * @example $("div").siblings()
+		 * @before <p>Hello</p><div><span>Hello Again</span></div><p>And Again</p>
+		 * @result [ <p>Hello</p>, <p>And Again</p> ]
+		 *
+		 * @name siblings
+		 * @type jQuery
+		 */
+
+		/**
+		 * Get a set of elements containing all of the unique siblings of each of the 
+		 * matched set of elements, and filtered by an expression.
+		 *
+		 * @example $("div").siblings("selected")
+		 * @before <div><span>Hello</span></div><p class="selected">Hello Again</p><p>And Again</p>
+		 * @result [ <p class="selected">Hello Again</p> ]
+		 *
+		 * @name siblings
+		 * @type jQuery
+		 * @param String expr An expression to filter the sibling Elements with
+		 */
 		siblings: jQuery.sibling
 	};
 	
@@ -926,7 +1180,7 @@ jQuery.extend({
 				
 				if ( m ) {
 					r = ret = jQuery.map( ret, jQuery.token[i+1] );
-					t = jQuery.trim(t).replace( re, "" );
+					t = jQuery.trim( t.replace( re, "" ) );
 					foundToken = true;
 				}
 			}
@@ -1058,10 +1312,14 @@ jQuery.extend({
 			
 			// Otherwise, find the expression to execute
 			else {
+				var f = jQuery.expr[m[1]];
+				if ( f.constructor != String )
+					f = jQuery.expr[m[1]][m[2]];
+					
 				// Build a custom macro to enclose it
 				eval("f = function(a,i){" + 
 					( m[1] == "@" ? "z=jQuery.attr(a,m[3]);" : "" ) + 
-					"return " + jQuery.expr[m[1]] + "}");
+					"return " + f + "}");
 				
 				// Execute it against the current filter
 				r = g( r, f );