Improved docs for blur() and focus(), mentioning the difference between calling the...

[jquery.git] / src / event / event.js

diff --git a/src/event/event.js b/src/event/event.js
index 921e524..fd4385c 100644 (file)
--- a/src/event/event.js
+++ b/src/event/event.js
@@ -101,6 +101,7 @@ jQuery.fn.extend({
         * otherwise $(document).ready() may not fire.
         *
         * You can have as many $(document).ready events on your page as you like.
+        * The functions are then executed in the order they were added.
         *
         * @example $(document).ready(function(){ Your code here... });
         *
@@ -228,9 +229,11 @@ new function(){
                /**
                 * Bind a function to the submit event of each matched element.
                 *
-                * @example $("p").submit( function() { alert("Hello"); } );
-                * @before <p>Hello</p>
-                * @result <p onsubmit="alert('Hello');">Hello</p>
+                * @example $("#myform").submit( function() {
+                *   return $("input", this).val().length > 0;
+                * } );
+                * @before <form id="myform"><input /></form>
+                * @desc Prevents the form submission when the input has no value entered.
                 *
                 * @name submit
                 * @type jQuery
@@ -242,9 +245,11 @@ new function(){
                 * Trigger the submit event of each matched element. This causes all of the functions
                 * that have been bound to thet submit event to be executed.
                 *
-                * @example $("p").submit();
-                * @before <p onsubmit="alert('Hello');">Hello</p>
-                * @result alert('Hello');
+                * Note: This does not execute the submit method of the form element! If you need to
+                * submit the form via code, you have to use the DOM method, eg. $("form")[0].submit();
+                *
+                * @example $("form").submit();
+                * @desc Triggers all submit events registered for forms, but does not submit the form
                 *
                 * @name submit
                 * @type jQuery
@@ -310,6 +315,9 @@ new function(){
                 * Trigger the focus event of each matched element. This causes all of the functions
                 * that have been bound to thet focus event to be executed.
                 *
+                * Note: This does not execute the focus method of the underlying elements! If you need to
+                * focus an element via code, you have to use the DOM method, eg. $("#myinput")[0].focus();
+                *
                 * @example $("p").focus();
                 * @before <p onfocus="alert('Hello');">Hello</p>
                 * @result alert('Hello');
@@ -650,6 +658,9 @@ new function(){
                 * Trigger the blur event of each matched element. This causes all of the functions
                 * that have been bound to thet blur event to be executed.
                 *
+                * Note: This does not execute the blur method of the underlying elements! If you need to
+                * blur an element via code, you have to use the DOM method, eg. $("#myinput")[0].blur();
+                *
                 * @example $("p").blur();
                 * @before <p onblur="alert('Hello');">Hello</p>
                 * @result alert('Hello');
@@ -1522,7 +1533,7 @@ new function(){
                 */
 
        var e = ("blur,focus,load,resize,scroll,unload,click,dblclick," +
-               "mousedown,mouseup,mousemove,mouseover,mouseout,change,reset,select," + 
+               "mousedown,mouseup,mousemove,mouseover,mouseout,change,select," + 
                "submit,keydown,keypress,keyup,error").split(",");
 
        // Go through all the event names, but make sure that
@@ -1548,7 +1559,7 @@ new function(){
                                element.unbind(o, handler);
                                element = null;
                                // apply original handler with the same arguments
-                               f.apply(this, arguments);
+                               return f.apply(this, arguments);
                        };
                        return this.bind(o, handler);
                };