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

1 files changed, 36 insertions, 118 deletions

diff --git a/src/fx/fx.js b/src/fx/fx.js
index 308567c23..e6b599611 100644
--- a/src/fx/fx.js
+++ b/src/fx/fx.js
@@ -4,33 +4,24 @@ jQuery.fn.extend({
 	_show: jQuery.fn.show,

 	

 	/**

-	 * Show all matched elements using a graceful animation.

+	 * Show all matched elements using a graceful animation and firing an

+	 * optional callback after completion.

+	 *

 	 * The height, width, and opacity of each of the matched elements 

 	 * are changed dynamically according to the specified speed.

 	 *

 	 * @example $("p").show("slow");

 	 *

-	 * @name show

-	 * @type jQuery

-	 * @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).

-	 * @cat Effects/Animations

-	 */

-	 

-	/**

-	 * Show all matched elements using a graceful animation and firing a callback

-	 * function after completion.

-	 * The height, width, and opacity of each of the matched elements 

-	 * are changed dynamically according to the specified speed.

-	 *

 	 * @example $("p").show("slow",function(){

 	 *   alert("Animation Done.");

 	 * });

 	 *

 	 * @name show

 	 * @type jQuery

-	 * @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).

-	 * @param Function callback A function to be executed whenever the animation completes.

+	 * @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).

+	 * @param Function callback (optional) A function to be executed whenever the animation completes.

 	 * @cat Effects/Animations

+	 * @see hide(String|Number,Function)

 	 */

 	show: function(speed,callback){

 		return speed ? this.animate({

@@ -42,33 +33,24 @@ jQuery.fn.extend({
 	_hide: jQuery.fn.hide,

 	

 	/**

-	 * Hide all matched elements using a graceful animation.

+	 * Hide all matched elements using a graceful animation and firing an

+	 * optional callback after completion.

+	 *

 	 * The height, width, and opacity of each of the matched elements 

 	 * are changed dynamically according to the specified speed.

 	 *

 	 * @example $("p").hide("slow");

 	 *

-	 * @name hide

-	 * @type jQuery

-	 * @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).

-	 * @cat Effects/Animations

-	 */

-	 

-	/**

-	 * Hide all matched elements using a graceful animation and firing a callback

-	 * function after completion.

-	 * The height, width, and opacity of each of the matched elements 

-	 * are changed dynamically according to the specified speed.

-	 *

 	 * @example $("p").hide("slow",function(){

 	 *   alert("Animation Done.");

 	 * });

 	 *

 	 * @name hide

 	 * @type jQuery

-	 * @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).

-	 * @param Function callback A function to be executed whenever the animation completes.

+	 * @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).

+	 * @param Function callback (optional) A function to be executed whenever the animation completes.

 	 * @cat Effects/Animations

+	 * @see show(String|Number,Function)

 	 */

 	hide: function(speed,callback){

 		return speed ? this.animate({

@@ -77,24 +59,14 @@ jQuery.fn.extend({
 	},

 	

 	/**

-	 * Reveal all matched elements by adjusting their height.

+	 * Reveal all matched elements by adjusting their height and firing an

+	 * optional callback after completion.

+	 *

 	 * Only the height is adjusted for this animation, causing all matched

 	 * elements to be revealed in a "sliding" manner.

 	 *

 	 * @example $("p").slideDown("slow");

 	 *

-	 * @name slideDown

-	 * @type jQuery

-	 * @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).

-	 * @cat Effects/Animations

-	 */

-	 

-	/**

-	 * Reveal all matched elements by adjusting their height and firing a callback

-	 * function after completion.

-	 * Only the height is adjusted for this animation, causing all matched

-	 * elements to be revealed in a "sliding" manner.

-	 *

 	 * @example $("p").slideDown("slow",function(){

 	 *   alert("Animation Done.");

 	 * });

@@ -102,7 +74,7 @@ jQuery.fn.extend({
 	 * @name slideDown

 	 * @type jQuery

 	 * @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).

-	 * @param Function callback A function to be executed whenever the animation completes.

+	 * @param Function callback (optional) A function to be executed whenever the animation completes.

 	 * @cat Effects/Animations

 	 */

 	slideDown: function(speed,callback){

@@ -110,24 +82,14 @@ jQuery.fn.extend({
 	},

 	

 	/**

-	 * Hide all matched elements by adjusting their height.

+	 * Hide all matched elements by adjusting their height and firing an

+	 * optional callback after completion.

+	 *

 	 * Only the height is adjusted for this animation, causing all matched

 	 * elements to be hidden in a "sliding" manner.

 	 *

 	 * @example $("p").slideUp("slow");

 	 *

-	 * @name slideUp

-	 * @type jQuery

-	 * @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).

-	 * @cat Effects/Animations

-	 */

-	 

-	/**

-	 * Hide all matched elements by adjusting their height and firing a callback

-	 * function after completion.

-	 * Only the height is adjusted for this animation, causing all matched

-	 * elements to be hidden in a "sliding" manner.

-	 *

 	 * @example $("p").slideUp("slow",function(){

 	 *   alert("Animation Done.");

 	 * });

@@ -135,7 +97,7 @@ jQuery.fn.extend({
 	 * @name slideUp

 	 * @type jQuery

 	 * @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).

-	 * @param Function callback A function to be executed whenever the animation completes.

+	 * @param Function callback (optional) A function to be executed whenever the animation completes.

 	 * @cat Effects/Animations

 	 */

 	slideUp: function(speed,callback){

@@ -143,24 +105,14 @@ jQuery.fn.extend({
 	},

 

 	/**

-	 * Toggle the visibility of all matched elements by adjusting their height.

+	 * Toggle the visibility of all matched elements by adjusting their height and firing an

+	 * optional callback after completion.

+	 *

 	 * Only the height is adjusted for this animation, causing all matched

 	 * elements to be hidden in a "sliding" manner.

 	 *

 	 * @example $("p").slideToggle("slow");

 	 *

-	 * @name slideToggle

-	 * @type jQuery

-	 * @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).

-	 * @cat Effects/Animations

-	 */

-	 

-	/**

-	 * Toggle the visibility of all matched elements by adjusting their height

-	 * and firing a callback function after completion.

-	 * Only the height is adjusted for this animation, causing all matched

-	 * elements to be hidden in a "sliding" manner.

-	 *

 	 * @example $("p").slideToggle("slow",function(){

 	 *   alert("Animation Done.");

 	 * });

@@ -168,7 +120,7 @@ jQuery.fn.extend({
 	 * @name slideToggle

 	 * @type jQuery

 	 * @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).

-	 * @param Function callback A function to be executed whenever the animation completes.

+	 * @param Function callback (optional) A function to be executed whenever the animation completes.

 	 * @cat Effects/Animations

 	 */

 	slideToggle: function(speed,callback){

@@ -179,26 +131,15 @@ jQuery.fn.extend({
 	},

 	

 	/**

-	 * Fade in all matched elements by adjusting their opacity.

+	 * Fade in all matched elements by adjusting their opacity and firing an

+	 * optional callback after completion.

+	 *

 	 * Only the opacity is adjusted for this animation, meaning that

 	 * all of the matched elements should already have some form of height

 	 * and width associated with them.

 	 *

 	 * @example $("p").fadeIn("slow");

 	 *

-	 * @name fadeIn

-	 * @type jQuery

-	 * @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).

-	 * @cat Effects/Animations

-	 */

-	 

-	/**

-	 * Fade in all matched elements by adjusting their opacity and firing a 

-	 * callback function after completion.

-	 * Only the opacity is adjusted for this animation, meaning that

-	 * all of the matched elements should already have some form of height

-	 * and width associated with them.

-	 *

 	 * @example $("p").fadeIn("slow",function(){

 	 *   alert("Animation Done.");

 	 * });

@@ -206,7 +147,7 @@ jQuery.fn.extend({
 	 * @name fadeIn

 	 * @type jQuery

 	 * @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).

-	 * @param Function callback A function to be executed whenever the animation completes.

+	 * @param Function callback (optional) A function to be executed whenever the animation completes.

 	 * @cat Effects/Animations

 	 */

 	fadeIn: function(speed,callback){

@@ -214,26 +155,15 @@ jQuery.fn.extend({
 	},

 	

 	/**

-	 * Fade out all matched elements by adjusting their opacity.

+	 * Fade out all matched elements by adjusting their opacity and firing an

+	 * optional callback after completion.

+	 *

 	 * Only the opacity is adjusted for this animation, meaning that

 	 * all of the matched elements should already have some form of height

 	 * and width associated with them.

 	 *

 	 * @example $("p").fadeOut("slow");

 	 *

-	 * @name fadeOut

-	 * @type jQuery

-	 * @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).

-	 * @cat Effects/Animations

-	 */

-	 

-	/**

-	 * Fade out all matched elements by adjusting their opacity and firing a 

-	 * callback function after completion.

-	 * Only the opacity is adjusted for this animation, meaning that

-	 * all of the matched elements should already have some form of height

-	 * and width associated with them.

-	 *

 	 * @example $("p").fadeOut("slow",function(){

 	 *   alert("Animation Done.");

 	 * });

@@ -241,7 +171,7 @@ jQuery.fn.extend({
 	 * @name fadeOut

 	 * @type jQuery

 	 * @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).

-	 * @param Function callback A function to be executed whenever the animation completes.

+	 * @param Function callback (optional) A function to be executed whenever the animation completes.

 	 * @cat Effects/Animations

 	 */

 	fadeOut: function(speed,callback){

@@ -249,27 +179,15 @@ jQuery.fn.extend({
 	},

 	

 	/**

-	 * Fade the opacity of all matched elements to a specified opacity.

+	 * Fade the opacity of all matched elements to a specified opacity and firing an

+	 * optional callback after completion.

+	 *

 	 * Only the opacity is adjusted for this animation, meaning that

 	 * all of the matched elements should already have some form of height

 	 * and width associated with them.

 	 *

 	 * @example $("p").fadeTo("slow", 0.5);

 	 *

-	 * @name fadeTo

-	 * @type jQuery

-	 * @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).

-	 * @param Number opacity The opacity to fade to (a number from 0 to 1).

-	 * @cat Effects/Animations

-	 */

-	 

-	/**

-	 * Fade the opacity of all matched elements to a specified opacity and 

-	 * firing a callback function after completion.

-	 * Only the opacity is adjusted for this animation, meaning that

-	 * all of the matched elements should already have some form of height

-	 * and width associated with them.

-	 *

 	 * @example $("p").fadeTo("slow", 0.5, function(){

 	 *   alert("Animation Done.");

 	 * });

@@ -278,7 +196,7 @@ jQuery.fn.extend({
 	 * @type jQuery

 	 * @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).

 	 * @param Number opacity The opacity to fade to (a number from 0 to 1).

-	 * @param Function callback A function to be executed whenever the animation completes.

+	 * @param Function callback (optional) A function to be executed whenever the animation completes.

 	 * @cat Effects/Animations

 	 */

 	fadeTo: function(speed,to,callback){