Improved docs for FX module, merging method descriptions and marking optional arguments

diff --git a/newandnoteworthy.txt b/newandnoteworthy.txt
index 722ded8..cf8dcd5 100644 (file)
--- a/newandnoteworthy.txt
+++ b/newandnoteworthy.txt
@@ -1,14 +1,14 @@
 New and Noteworthy
 -----------------
 
-1.0.5/1.1
+1.1
 -----
 
  - Massive speed-ups (4x-10x) in the selector engine 
  - Fixed synchronous requests
  - $.get, $.getIfModified, $.post, $.getScript and $.getJSON now all pass through the XMLHttpRequest as returned by $.ajax
- - Improved AJAX docs (eg. more examples for $.ajax
- - Improved event fixingFixed event fixing (Opera provides event.srcElement, must ignore it if target is available; only create pageX if clientX is available)
+ - Improved AJAX docs (eg. more examples for $.ajax)
+ - Improved event fixing (Opera provides event.srcElement, must ignore it if target is available; only create pageX if clientX is available)
  - Fixed ID with context selectors (eg. div #id doesn't ignore "div" anymore)
  - Fixed nth-child selectors to start on the right number
  - Improved jQuery.merge to avoid unnecessary loops
@@ -17,6 +17,8 @@ New and Noteworthy
  - Implemented a better error handling for ajax requests. Exceptions caused by dropping connections are now handled, too.
  - Added global settings for AJAX (in addition to timeout), use $.ajaxSetup() to modify them
  - You can now unbind event handlers from within themselves
+ - Documented filter(Function)
+ - Improved docs for FX module, merging method descriptions and marking optional arguments
 
 1.0.4
 -----

diff --git a/src/fx/fx.js b/src/fx/fx.js
index 308567c..e6b5996 100644 (file)
--- a/src/fx/fx.js
+++ b/src/fx/fx.js
@@ -4,33 +4,24 @@ jQuery.fn.extend({
        _show: jQuery.fn.show,\r
        \r
        /**\r
-        * Show all matched elements using a graceful animation.\r
+        * Show all matched elements using a graceful animation and firing an\r
+        * optional callback after completion.\r
+        *\r
         * The height, width, and opacity of each of the matched elements \r
         * are changed dynamically according to the specified speed.\r
         *\r
         * @example $("p").show("slow");\r
         *\r
-        * @name show\r
-        * @type jQuery\r
-        * @param Object speed A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).\r
-        * @cat Effects/Animations\r
-        */\r
-        \r
-       /**\r
-        * Show all matched elements using a graceful animation and firing a callback\r
-        * function after completion.\r
-        * The height, width, and opacity of each of the matched elements \r
-        * are changed dynamically according to the specified speed.\r
-        *\r
         * @example $("p").show("slow",function(){\r
         *   alert("Animation Done.");\r
         * });\r
         *\r
         * @name show\r
         * @type jQuery\r
-        * @param Object speed A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).\r
-        * @param Function callback A function to be executed whenever the animation completes.\r
+        * @param String|Number speed A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).\r
+        * @param Function callback (optional) A function to be executed whenever the animation completes.\r
         * @cat Effects/Animations\r
+        * @see hide(String|Number,Function)\r
         */\r
        show: function(speed,callback){\r
                return speed ? this.animate({\r
@@ -42,33 +33,24 @@ jQuery.fn.extend({
        _hide: jQuery.fn.hide,\r
        \r
        /**\r
-        * Hide all matched elements using a graceful animation.\r
+        * Hide all matched elements using a graceful animation and firing an\r
+        * optional callback after completion.\r
+        *\r
         * The height, width, and opacity of each of the matched elements \r
         * are changed dynamically according to the specified speed.\r
         *\r
         * @example $("p").hide("slow");\r
         *\r
-        * @name hide\r
-        * @type jQuery\r
-        * @param Object speed A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).\r
-        * @cat Effects/Animations\r
-        */\r
-        \r
-       /**\r
-        * Hide all matched elements using a graceful animation and firing a callback\r
-        * function after completion.\r
-        * The height, width, and opacity of each of the matched elements \r
-        * are changed dynamically according to the specified speed.\r
-        *\r
         * @example $("p").hide("slow",function(){\r
         *   alert("Animation Done.");\r
         * });\r
         *\r
         * @name hide\r
         * @type jQuery\r
-        * @param Object speed A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).\r
-        * @param Function callback A function to be executed whenever the animation completes.\r
+        * @param String|Number speed A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).\r
+        * @param Function callback (optional) A function to be executed whenever the animation completes.\r
         * @cat Effects/Animations\r
+        * @see show(String|Number,Function)\r
         */\r
        hide: function(speed,callback){\r
                return speed ? this.animate({\r
@@ -77,24 +59,14 @@ jQuery.fn.extend({
        },\r
        \r
        /**\r
-        * Reveal all matched elements by adjusting their height.\r
+        * Reveal all matched elements by adjusting their height and firing an\r
+        * optional callback after completion.\r
+        *\r
         * Only the height is adjusted for this animation, causing all matched\r
         * elements to be revealed in a "sliding" manner.\r
         *\r
         * @example $("p").slideDown("slow");\r
         *\r
-        * @name slideDown\r
-        * @type jQuery\r
-        * @param Object speed A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).\r
-        * @cat Effects/Animations\r
-        */\r
-        \r
-       /**\r
-        * Reveal all matched elements by adjusting their height and firing a callback\r
-        * function after completion.\r
-        * Only the height is adjusted for this animation, causing all matched\r
-        * elements to be revealed in a "sliding" manner.\r
-        *\r
         * @example $("p").slideDown("slow",function(){\r
         *   alert("Animation Done.");\r
         * });\r
@@ -102,7 +74,7 @@ jQuery.fn.extend({
         * @name slideDown\r
         * @type jQuery\r
         * @param Object speed A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).\r
-        * @param Function callback A function to be executed whenever the animation completes.\r
+        * @param Function callback (optional) A function to be executed whenever the animation completes.\r
         * @cat Effects/Animations\r
         */\r
        slideDown: function(speed,callback){\r
@@ -110,24 +82,14 @@ jQuery.fn.extend({
        },\r
        \r
        /**\r
-        * Hide all matched elements by adjusting their height.\r
+        * Hide all matched elements by adjusting their height and firing an\r
+        * optional callback after completion.\r
+        *\r
         * Only the height is adjusted for this animation, causing all matched\r
         * elements to be hidden in a "sliding" manner.\r
         *\r
         * @example $("p").slideUp("slow");\r
         *\r
-        * @name slideUp\r
-        * @type jQuery\r
-        * @param Object speed A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).\r
-        * @cat Effects/Animations\r
-        */\r
-        \r
-       /**\r
-        * Hide all matched elements by adjusting their height and firing a callback\r
-        * function after completion.\r
-        * Only the height is adjusted for this animation, causing all matched\r
-        * elements to be hidden in a "sliding" manner.\r
-        *\r
         * @example $("p").slideUp("slow",function(){\r
         *   alert("Animation Done.");\r
         * });\r
@@ -135,7 +97,7 @@ jQuery.fn.extend({
         * @name slideUp\r
         * @type jQuery\r
         * @param Object speed A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).\r
-        * @param Function callback A function to be executed whenever the animation completes.\r
+        * @param Function callback (optional) A function to be executed whenever the animation completes.\r
         * @cat Effects/Animations\r
         */\r
        slideUp: function(speed,callback){\r
@@ -143,24 +105,14 @@ jQuery.fn.extend({
        },\r
 \r
        /**\r
-        * Toggle the visibility of all matched elements by adjusting their height.\r
+        * Toggle the visibility of all matched elements by adjusting their height and firing an\r
+        * optional callback after completion.\r
+        *\r
         * Only the height is adjusted for this animation, causing all matched\r
         * elements to be hidden in a "sliding" manner.\r
         *\r
         * @example $("p").slideToggle("slow");\r
         *\r
-        * @name slideToggle\r
-        * @type jQuery\r
-        * @param Object speed A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).\r
-        * @cat Effects/Animations\r
-        */\r
-        \r
-       /**\r
-        * Toggle the visibility of all matched elements by adjusting their height\r
-        * and firing a callback function after completion.\r
-        * Only the height is adjusted for this animation, causing all matched\r
-        * elements to be hidden in a "sliding" manner.\r
-        *\r
         * @example $("p").slideToggle("slow",function(){\r
         *   alert("Animation Done.");\r
         * });\r
@@ -168,7 +120,7 @@ jQuery.fn.extend({
         * @name slideToggle\r
         * @type jQuery\r
         * @param Object speed A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).\r
-        * @param Function callback A function to be executed whenever the animation completes.\r
+        * @param Function callback (optional) A function to be executed whenever the animation completes.\r
         * @cat Effects/Animations\r
         */\r
        slideToggle: function(speed,callback){\r
@@ -179,26 +131,15 @@ jQuery.fn.extend({
        },\r
        \r
        /**\r
-        * Fade in all matched elements by adjusting their opacity.\r
+        * Fade in all matched elements by adjusting their opacity and firing an\r
+        * optional callback after completion.\r
+        *\r
         * Only the opacity is adjusted for this animation, meaning that\r
         * all of the matched elements should already have some form of height\r
         * and width associated with them.\r
         *\r
         * @example $("p").fadeIn("slow");\r
         *\r
-        * @name fadeIn\r
-        * @type jQuery\r
-        * @param Object speed A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).\r
-        * @cat Effects/Animations\r
-        */\r
-        \r
-       /**\r
-        * Fade in all matched elements by adjusting their opacity and firing a \r
-        * callback function after completion.\r
-        * Only the opacity is adjusted for this animation, meaning that\r
-        * all of the matched elements should already have some form of height\r
-        * and width associated with them.\r
-        *\r
         * @example $("p").fadeIn("slow",function(){\r
         *   alert("Animation Done.");\r
         * });\r
@@ -206,7 +147,7 @@ jQuery.fn.extend({
         * @name fadeIn\r
         * @type jQuery\r
         * @param Object speed A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).\r
-        * @param Function callback A function to be executed whenever the animation completes.\r
+        * @param Function callback (optional) A function to be executed whenever the animation completes.\r
         * @cat Effects/Animations\r
         */\r
        fadeIn: function(speed,callback){\r
@@ -214,26 +155,15 @@ jQuery.fn.extend({
        },\r
        \r
        /**\r
-        * Fade out all matched elements by adjusting their opacity.\r
+        * Fade out all matched elements by adjusting their opacity and firing an\r
+        * optional callback after completion.\r
+        *\r
         * Only the opacity is adjusted for this animation, meaning that\r
         * all of the matched elements should already have some form of height\r
         * and width associated with them.\r
         *\r
         * @example $("p").fadeOut("slow");\r
         *\r
-        * @name fadeOut\r
-        * @type jQuery\r
-        * @param Object speed A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).\r
-        * @cat Effects/Animations\r
-        */\r
-        \r
-       /**\r
-        * Fade out all matched elements by adjusting their opacity and firing a \r
-        * callback function after completion.\r
-        * Only the opacity is adjusted for this animation, meaning that\r
-        * all of the matched elements should already have some form of height\r
-        * and width associated with them.\r
-        *\r
         * @example $("p").fadeOut("slow",function(){\r
         *   alert("Animation Done.");\r
         * });\r
@@ -241,7 +171,7 @@ jQuery.fn.extend({
         * @name fadeOut\r
         * @type jQuery\r
         * @param Object speed A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).\r
-        * @param Function callback A function to be executed whenever the animation completes.\r
+        * @param Function callback (optional) A function to be executed whenever the animation completes.\r
         * @cat Effects/Animations\r
         */\r
        fadeOut: function(speed,callback){\r
@@ -249,27 +179,15 @@ jQuery.fn.extend({
        },\r
        \r
        /**\r
-        * Fade the opacity of all matched elements to a specified opacity.\r
+        * Fade the opacity of all matched elements to a specified opacity and firing an\r
+        * optional callback after completion.\r
+        *\r
         * Only the opacity is adjusted for this animation, meaning that\r
         * all of the matched elements should already have some form of height\r
         * and width associated with them.\r
         *\r
         * @example $("p").fadeTo("slow", 0.5);\r
         *\r
-        * @name fadeTo\r
-        * @type jQuery\r
-        * @param Object speed A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).\r
-        * @param Number opacity The opacity to fade to (a number from 0 to 1).\r
-        * @cat Effects/Animations\r
-        */\r
-        \r
-       /**\r
-        * Fade the opacity of all matched elements to a specified opacity and \r
-        * firing a callback function after completion.\r
-        * Only the opacity is adjusted for this animation, meaning that\r
-        * all of the matched elements should already have some form of height\r
-        * and width associated with them.\r
-        *\r
         * @example $("p").fadeTo("slow", 0.5, function(){\r
         *   alert("Animation Done.");\r
         * });\r
@@ -278,7 +196,7 @@ jQuery.fn.extend({
         * @type jQuery\r
         * @param Object speed A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).\r
         * @param Number opacity The opacity to fade to (a number from 0 to 1).\r
-        * @param Function callback A function to be executed whenever the animation completes.\r
+        * @param Function callback (optional) A function to be executed whenever the animation completes.\r
         * @cat Effects/Animations\r
         */\r
        fadeTo: function(speed,to,callback){\r