X-Git-Url: http://git.asbjorn.it/?a=blobdiff_plain;f=src%2Fjquery%2Fjquery.js;h=74b912e665bc8de7e43c1f247a6e1b47bdebb32f;hb=1c42201d7aba027afeaec8bef5e026d74ce38a7b;hp=64ade0a6830cf9d999ba83ad99b193be1cf83e59;hpb=68d8e53d8751c095fcc148cb52aae472a6e60c26;p=jquery.git

diff --git a/src/jquery/jquery.js b/src/jquery/jquery.js
index 64ade0a..74b912e 100644
--- a/src/jquery/jquery.js
+++ b/src/jquery/jquery.js
@@ -356,6 +356,9 @@ jQuery.fn = jQuery.prototype = {
 	 * This method makes it easy to retrieve a property value
 	 * from the first matched element.
 	 *
+	 * If the element does not have an attribute with such a
+ 	 * name, undefined is returned.
+	 *
 	 * @example $("img").attr("src");
 	 * @before <img src="test.jpg"/>
 	 * @result test.jpg
@@ -387,8 +390,6 @@ jQuery.fn = jQuery.prototype = {
 	/**
 	 * Set a single property to a value, on all matched elements.
 	 *
-	 * Can compute values provided as ${formula}, see second example.
-	 *
 	 * Note that you can't set the name property of input elements in IE.
 	 * Use $(html) or .append(html) or .html(html) to create elements
 	 * on the fly including the name property.
@@ -398,11 +399,6 @@ jQuery.fn = jQuery.prototype = {
 	 * @result <img src="test.jpg"/>
 	 * @desc Sets src attribute to all images.
 	 *
-	 * @example $("img").attr("title", "${this.src}");
-	 * @before <img src="test.jpg" />
-	 * @result <img src="test.jpg" title="test.jpg" />
-	 * @desc Sets title attribute from src attribute, a shortcut for attr(String,Function)
-	 *
 	 * @name attr
 	 * @type jQuery
 	 * @param String key The name of the property to set.
@@ -413,7 +409,9 @@ jQuery.fn = jQuery.prototype = {
 	/**
 	 * Set a single property to a computed value, on all matched elements.
 	 *
-	 * Instead of a value, a function is provided, that computes the value.
+	 * Instead of supplying a string value as described
+	 * [[DOM/Attributes#attr.28_key.2C_value_.29|above]],
+	 * a function is provided that computes the value.
 	 *
 	 * @example $("img").attr("title", function() { return this.src });
 	 * @before <img src="test.jpg" />
@@ -770,12 +768,17 @@ jQuery.fn = jQuery.prototype = {
 	},
 
 	/**
-	 * 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.
+	 * Revert the most recent 'destructive' operation, changing the set of matched elements
+	 * to its previous state (right before the destructive operation).
 	 *
 	 * If there was no destructive operation before, an empty set is returned.
 	 *
+	 * A 'destructive' operation is any operation that changes the set of
+	 * matched jQuery elements. These functions are: <code>add</code>,
+	 * <code>children</code>, <code>clone</code>, <code>filter</code>,
+	 * <code>find</code>, <code>not</code>, <code>next</code>,
+	 * <code>parent</code>, <code>parents</code>, <code>prev</code> and <code>siblings</code>.
+	 *
 	 * @example $("p").find("span").end();
 	 * @before <p><span>Hello</span>, how are you?</p>
 	 * @result [ <p>...</p> ]
@@ -926,6 +929,13 @@ jQuery.fn = jQuery.prototype = {
 	 * of matched elements. This method is used to remove one or more
 	 * elements from a jQuery object.
 	 *
+	 * Please note: the expression cannot use a reference to the
+	 * element name. See the two examples below.
+	 *
+	 * This will not work: $(".res img").not("img[@src$=on]")
+	 *
+	 * This will: $(".res img").not("[@src$=on]"); // also could be written $(".res img:not([@src$=on])")
+	 *
 	 * @example $("p").not( $("div p.selected") )
 	 * @before <div><p>Hello</p><p class="selected">Hello Again</p></div>
 	 * @result [ <p>Hello</p> ]
@@ -954,8 +964,12 @@ jQuery.fn = jQuery.prototype = {
 	 * to the set of matched elements.
 	 *
 	 * @example $("p").add("span")
-	 * @before <p>Hello</p><span>Hello Again</span>
-	 * @result [ <p>Hello</p>, <span>Hello Again</span> ]
+	 * @before (HTML) <p>Hello</p><span>Hello Again</span>
+	 * @result (jQuery object matching 2 elements) [ <p>Hello</p>, <span>Hello Again</span> ]
+	 * @desc Compare the above result to the result of <code>$('p')</code>,
+	 * which would just result in <code><nowiki>[ <p>Hello</p> ]</nowiki></code>.
+	 * Using add(), matched elements of <code>$('span')</code> are simply
+	 * added to the returned jQuery-object.
 	 *
 	 * @name add
 	 * @type jQuery
@@ -1032,7 +1046,14 @@ jQuery.fn = jQuery.prototype = {
 	},
 	
 	/**
-	 * Get the current value of the first matched element.
+	 * Get the content of the value attribute of the first matched element.
+	 *
+	 * Use caution when relying on this function to check the value of
+	 * multiple-select elements and checkboxes in a form. While it will
+	 * still work as intended, it may not accurately represent the value
+	 * the server will receive because these elements may send an array
+	 * of values. For more robust handling of field values, see the
+	 * [http://www.malsup.com/jquery/form/#fields fieldValue function of the Form Plugin].
 	 *
 	 * @example $("input").val();
 	 * @before <input type="text" value="some text"/>
@@ -1044,7 +1065,7 @@ jQuery.fn = jQuery.prototype = {
 	 */
 	
 	/**
-	 * Set the value of every matched element.
+	 * 	Set the value attribute of every matched element.
 	 *
 	 * @example $("input").val("test");
 	 * @before <input type="text" value="some text"/>
@@ -1251,7 +1272,7 @@ jQuery.extend({
 	},
 
 	/**
-	 * A generic iterator function, which can be used to seemlessly
+	 * A generic iterator function, which can be used to seamlessly
 	 * iterate over both objects and arrays. This function is not the same
 	 * as $().each() - which is used to iterate, exclusively, over a jQuery
 	 * object. This function can be used to iterate over anything.
@@ -1778,7 +1799,7 @@ new function() {
  * Get a set of elements containing the unique parents of the matched
  * set of elements.
  *
- * Can be filtered with an optional expressions.
+ * You may use an optional expression to filter the set of parent elements that will match.
  *
  * @example $("p").parent()
  * @before <div><p>Hello</p><p>Hello</p></div>
@@ -1800,7 +1821,7 @@ new function() {
  * Get a set of elements containing the unique ancestors of the matched
  * set of elements (except for the root element).
  *
- * Can be filtered with an optional expressions.
+ * The matched elements can be filtered with an optional expression.
  *
  * @example $("span").parents()
  * @before <html><body><div><p><span>Hello</span></p><span>Hello Again</span></div></body></html>
@@ -1822,9 +1843,10 @@ new function() {
  * 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.
+ * It only returns the very next sibling for each element, not all
+ * next siblings.
  *
- * Can be filtered with an optional expressions.
+ * You may provide an optional expression to filter the match.
  *
  * @example $("p").next()
  * @before <p>Hello</p><p>Hello Again</p><div><span>And Again</span></div>
@@ -1846,9 +1868,9 @@ new function() {
  * Get a set of elements containing the unique previous siblings of each of the
  * matched set of elements.
  *
- * Can be filtered with an optional expressions.
+ * Use an optional expression to filter the matched set.
  *
- * It only returns the immediately previous sibling, not all previous siblings.
+ * 	Only the immediately previous sibling is returned, not all previous siblings.
  *
  * @example $("p").prev()
  * @before <p>Hello</p><div><span>Hello Again</span></div><p>And Again</p>
@@ -1892,7 +1914,8 @@ new function() {
  * Get a set of elements containing all of the unique children of each of the
  * matched set of elements.
  *
- * Can be filtered with an optional expressions.
+ * This set can be filtered with an optional expression that will cause
+ * only elements matching the selector to be collected.
  *
  * @example $("div").children()
  * @before <p>Hello</p><div><span>Hello Again</span></div><p>And Again</p>
@@ -2245,7 +2268,7 @@ jQuery.each( [ "eq", "lt", "gt", "contains" ], function(i,n){
  */
 
 /**
- * Set the CSS width of every matched element. If no explicit unit
+ * Set the CSS height of every matched element. If no explicit unit
  * was specified (like 'em' or '%') then "px" is added to the width.
  *
  * @example $("p").height(20);