Index: /CKEditor/trunk/_source/core/tools.js
===================================================================
--- /CKEditor/trunk/_source/core/tools.js	(revision 4682)
+++ /CKEditor/trunk/_source/core/tools.js	(revision 4683)
@@ -20,4 +20,20 @@
 	CKEDITOR.tools =
 	{
+		/**
+		 * Compare the elements of two arrays.
+		 * @param {Array} arrayA An array to be compared.
+		 * @param {Array} arrayB The other array to be compared.
+		 * @returns {Boolean} "true" is the arrays have the same lenght and
+		 *		their elements match.
+		 * @example
+		 * var a = [ 1, 'a', 3 ];
+		 * var b = [ 1, 3, 'a' ];
+		 * var c = [ 1, 'a', 3 ];
+		 * var d = [ 1, 'a', 3, 4 ];
+		 *
+		 * alert( CKEDITOR.tools.arrayCompare( a, b ) );  // false
+		 * alert( CKEDITOR.tools.arrayCompare( a, c ) );  // true
+		 * alert( CKEDITOR.tools.arrayCompare( a, d ) );  // false
+		 */
 		arrayCompare : function( arrayA, arrayB )
 		{
@@ -462,4 +478,22 @@
 				},
 
+		/**
+		 * Creates a function that will always execute in the context of a
+		 * specified object.
+		 * @param {Function} func The function to be executed.
+		 * @param {Object} obj The object to which bind the execution context.
+		 * @returns {Function} The function that can be used to execute the
+		 *		"func" function in the context of "obj".
+		 * @example
+		 * var obj = { text : 'My Object' };
+		 *
+		 * function alertText()
+		 * {
+		 *     alert( this.text );
+		 * }
+		 *
+		 * var newFunc = <b>CKEDITOR.tools.bind( alertText, obj )</b>;
+		 * newFunc();  // Alerts "My Object".
+		 */
 		bind : function( func, obj )
 		{
@@ -473,9 +507,9 @@
 		 * <li> Static fields </li>
 		 * <li> Private fields </li>
-		 * <li> Public(prototype) fields </li>
+		 * <li> Public (prototype) fields </li>
 		 * <li> Chainable base class constructor </li>
 		 * </ul>
-		 *
-		 * @param {Object} definiton (Optional)The class definiton object.
+		 * @param {Object} definiton The class definiton object.
+		 * @returns {Function} A class-like JavaScript function.
 		 */
 		createClass : function( definition )
@@ -530,4 +564,20 @@
 		},
 
+		/**
+		 * Creates a function reference that can be called later using
+		 * CKEDITOR.tools.callFunction. This approach is specially useful to
+		 * make DOM attribute function calls to JavaScript defined functions.
+		 * @param {Function} fn The function to be executed on call.
+		 * @param {Object} [scope] The object to have the context on "fn" execution.
+		 * @returns {Number} A unique reference to be used in conjuction with
+		 *		CKEDITOR.tools.callFunction.
+		 * @example
+		 * var ref = <b>CKEDITOR.tools.addFunction</b>(
+		 *     function()
+		 *     {
+		 *         alert( 'Hello!');
+		 *     });
+		 * CKEDITOR.tools.callFunction( ref );  // Hello!
+		 */
 		addFunction : function( fn, scope )
 		{
@@ -538,8 +588,24 @@
 		},
 
-		callFunction : function( index )
-		{
-			var fn = functions[ index ];
-			return fn.apply( window, Array.prototype.slice.call( arguments, 1 ) );
+		/**
+		 * Executes a function based on the reference created with
+		 * CKEDITOR.tools.addFunction.
+		 * @param {Number} ref The function reference created with
+		 *		CKEDITOR.tools.addFunction.
+		 * @param {[Any,[Any,...]} params Any number of parameters to be passed
+		 *		to the executed function.
+		 * @returns {Any} The return value of the function.
+		 * @example
+		 * var ref = CKEDITOR.tools.addFunction(
+		 *     function()
+		 *     {
+		 *         alert( 'Hello!');
+		 *     });
+		 * <b>CKEDITOR.tools.callFunction( ref )</b>;  // Hello!
+		 */
+		callFunction : function( ref )
+		{
+			var fn = functions[ ref ];
+			return fn && fn.apply( window, Array.prototype.slice.call( arguments, 1 ) );
 		},