Document functions with callback syntax

Source/Core/Event.js

@@ -38,7 +38,7 @@ define([
          * @memberof Event.prototype
          * @type {Number}
          */
-        numberOfListeners: {
+        numberOfListeners : {
             get : function() {
                 return this._listeners.length;
             }
@@ -52,8 +52,8 @@ define([
      *
      * @param {Function} listener The function to be executed when the event is raised.
      * @param {Object} [scope] An optional object scope to serve as the <code>this</code>
-     * pointer in which the listener function will execute.
-     * @returns {Function} A function that will remove this event listener when invoked.
+     *        pointer in which the listener function will execute.
+     * @returns {Event~RemoveCallback} A function that will remove this event listener when invoked.
      *
      * @see Event#raiseEvent
      * @see Event#removeEventListener
@@ -128,5 +128,10 @@ define([
         }
     };
 
+    /**
+     * A function that removes a listener.
+     * @callback Event~RemoveCallback
+     */
+
     return Event;
 });

Source/Core/EventHelper.js

@@ -36,8 +36,8 @@ define([
      * @param {Event} event The event to attach to.
      * @param {Function} listener The function to be executed when the event is raised.
      * @param {Object} [scope] An optional object scope to serve as the <code>this</code>
-     * pointer in which the listener function will execute.
-     * @returns {Function} A function that will remove this event listener when invoked.
+     *        pointer in which the listener function will execute.
+     * @returns {EventHelper~RemoveCallback} A function that will remove this event listener when invoked.
      *
      * @see Event#addEventListener
      */
@@ -72,5 +72,10 @@ define([
         removalFunctions.length = 0;
     };
 
+    /**
+     * A function that removes a listener.
+     * @callback EventHelper~RemoveCallback
+     */
+
     return EventHelper;
 });

Source/Core/Queue.js

@@ -73,7 +73,7 @@ define(function() {
     /**
      * Sort the items in the queue in-place.
      *
-     * @param {Function} compareFunction a function that defines the sort order.
+     * @param {Queue~Comparator} compareFunction a function that defines the sort order.
      */
     Queue.prototype.sort = function(compareFunction) {
         if (this._offset > 0) {
@@ -85,5 +85,21 @@ define(function() {
         this._array.sort(compareFunction);
     };
 
+    /**
+     * A function used to compare two items while sorting a queue.
+     * @callback Queue~Comparator
+     *
+     * @param {Object} a An item in the array.
+     * @param {Object} b An item in the array.
+     * @returns {Number} Returns a negative value if <code>a</code> is less than <code>b</code>,
+     *          a positive value if <code>a</code> is greater than <code>b</code>, or
+     *          0 if <code>a</code> is equal to <code>b</code>.
+     *
+     * @example
+     * function compareNumbers(a, b) {
+     *     return a - b;
+     * }
+     */
+
     return Queue;
 });

Source/Core/TileProviderError.js

@@ -94,7 +94,7 @@ define([
      *        error is not specific to a particular tile.
      * @param {Number} level The level-of-detail of the tile that experienced the error, or undefined if the
      *        error is not specific to a particular tile.
-     * @param {Function} retryFunction The function to call to retry the operation.  If undefined, the
+     * @param {TileProviderError~RetryFunction} retryFunction The function to call to retry the operation.  If undefined, the
      *        operation will not be retried.
      * @returns {TileProviderError} The error instance that was passed to the event listeners and that
      *          should be passed to this function the next time it is called for the same error in order
@@ -141,5 +141,10 @@ define([
         }
     };
 
+    /**
+     * A function that will be called to retry the operation.
+     * @callback TileProviderError~RetryFunction
+     */
+
     return TileProviderError;
 });

Source/Core/binarySearch.js

@@ -14,20 +14,16 @@ define([
      *
      * @param {Array} array The sorted array to search.
      * @param {Object} itemToFind The item to find in the array.
-     *
-     * @param {Function} comparator The function to use to compare the item to elements in the array.
-     *        The first parameter passed to the comparator function is an item in the array, the
-     *        second is <code>itemToFind</code>.  If the array item is less than <code>itemToFind</code>,
-     *        the function should return a negative value.  If it is greater, the function should return
-     *        a positive value.  If the items are equal, it should return 0.
+     * @param {binarySearch~Comparator} comparator The function to use to compare the item to
+     *        elements in the array.
      * @returns {Number} The index of <code>itemToFind</code> in the array, if it exists.  If <code>itemToFind</code>
      *        does not exist, the return value is a negative number which is the bitwise complement (~)
      *        of the index before which the itemToFind should be inserted in order to maintain the
      *        sorted order of the array.
      *
      * @example
      * // Create a comparator function to search through an array of numbers.
-     * var comparator = function (a, b) {
+     * var comparator = function(a, b) {
      *     return a - b;
      * };
      * var numbers = [0, 2, 4, 6, 8];
@@ -67,5 +63,21 @@ define([
         return ~(high + 1);
     };
 
+    /**
+     * A function used to compare two items while performing a binary search.
+     * @callback binarySearch~Comparator
+     *
+     * @param {Object} a An item in the array.
+     * @param {Object} b The item being searched for.
+     * @returns {Number} Returns a negative value if <code>a</code> is less than <code>b</code>,
+     *          a positive value if <code>a</code> is greater than <code>b</code>, or
+     *          0 if <code>a</code> is equal to <code>b</code>.
+     *
+     * @example
+     * function compareNumbers(a, b) {
+     *     return a - b;
+     * }
+     */
+
     return binarySearch;
 });

Source/Core/mergeSort.js

@@ -60,18 +60,15 @@ define([
      * @exports mergeSort
      *
      * @param {Array} array The array to sort.
-     * @param {Function} comparator The function to use to compare the item to elements in the array.
-     *        If the first parameter is less than the second parameter, the function should return a
-     *        negative value.  If it is greater, the function should return a positive value.  If the
-     *        items are equal, it should return 0.
-     * @param {Object} [userDefinedObject] An object to pass as the third parameter to comparator.
+     * @param {mergeSort~Comparator} comparator The function to use to compare elements in the array.
+     * @param {Object} [userDefinedObject] An object to pass as the third parameter to <code>comparator</code>.
      *
      * @example
-     * // Sort an array of numbers in increasing order
-     * var array = // Array of bounding spheres in world coordinates
+     * // Assume array contains BoundingSpheres in world coordinates.
+     * // Sort them in ascending order of distance from the camera.
      * var position = camera.positionWC;
      * mergeSort(array, function(a, b, position) {
-     *     return BoundingSphere.distanceSquaredTo(b.sphere, position) - BounsingSphere.distanceSquaredTo(a.sphere, position);
+     *     return BoundingSphere.distanceSquaredTo(b, position) - BoundingSphere.distanceSquaredTo(a, position);
      * }, position);
      */
     var mergeSort = function(array, comparator, userDefinedObject) {
@@ -98,5 +95,22 @@ define([
         rightScratchArray.length = 0;
     };
 
+    /**
+     * A function used to compare two items while performing a merge sort.
+     * @callback mergeSort~Comparator
+     *
+     * @param {Object} a An item in the array.
+     * @param {Object} b An item in the array.
+     * @param {Object} [userDefinedObject] An object that was passed to {@link mergeSort}.
+     * @returns {Number} Returns a negative value if <code>a</code> is less than <code>b</code>,
+     *          a positive value if <code>a</code> is greater than <code>b</code>, or
+     *          0 if <code>a</code> is equal to <code>b</code>.
+     *
+     * @example
+     * function compareNumbers(a, b, userDefinedObject) {
+     *     return a - b;
+     * }
+     */
+
     return mergeSort;
 });

Source/Core/requestAnimationFrame.js

@@ -43,7 +43,7 @@ define([
      *
      * @exports requestAnimationFrame
      *
-     * @param {Function} callback The function to call when animation is ready.
+     * @param {requestAnimationFrame~Callback} callback The function to call when the next frame should be drawn.
      * @returns An ID that can be passed to {@link cancelAnimationFrame} to cancel the request.
      *
      * @see {@link http://www.w3.org/TR/animation-timing/#the-WindowAnimationTiming-interface|The WindowAnimationTiming interface}
@@ -64,5 +64,12 @@ define([
         return implementation(callback);
     };
 
+    /**
+     * A function that will be called when the next frame should be drawn.
+     * @callback requestAnimationFrame~Callback
+     *
+     * @param {Number} timestamp A timestamp for the frame, in milliseconds.
+     */
+
     return requestAnimationFrame;
 });

Source/Core/throttleRequestByServer.js

@@ -23,36 +23,37 @@ define([
 
     /**
      * Because browsers throttle the number of parallel requests allowed to each server,
-     * this function tracks the number of active requests that have been made, and
+     * this function tracks the number of active requests in progress to each server, and
      * returns undefined immediately if the request would exceed the maximum, allowing
-     * the caller to retry later.
+     * the caller to retry later, instead of queueing indefinitely under the browser's control.
      *
      * @exports throttleRequestByServer
      *
      * @param {String} url The URL to request.
-     * @param {Function} requestFunction The actual function that makes the request.
-     * This function is expected to return a Promise for the requested data.
-     * @returns {Promise} Either undefined, meaning the request would exceed the maximum
-     * number of parallel requests, or a Promise that returns the requested data.
+     * @param {throttleRequestByServer~RequestFunction} requestFunction The actual function that
+     *        makes the request.
+     * @returns {Promise} Either undefined, meaning the request would exceed the maximum number of
+     *          parallel requests, or a Promise for the requested data.
      *
      * @see {@link http://wiki.commonjs.org/wiki/Promises/A|CommonJS Promises/A}
      *
      * @example
      * // throttle requests for an image
-     * var promise = Cesium.throttleRequestByServer(
-     *     'http://madeupserver.agi.com/myImage.png',
-     *     function(url) {
-     *        return Cesium.loadImage(url);
-     *     });
+     * var url = 'http://madeupserver.example.com/myImage.png';
+     * var requestFunction = function(url) {
+     *   // in this simple example, loadImage could be used directly as requestFunction.
+     *   return Cesium.loadImage(url);
+     * };
+     * var promise = Cesium.throttleRequestByServer(url, requestFunction);
      * if (!Cesium.defined(promise)) {
-     *     // too many active requests, try again later.
+     *   // too many active requests in progress, try again later.
      * } else {
-     *     Cesium.when(promise, function(image) {
-     *         // handle loaded image
-     *     });
+     *   promise.then(function(image) {
+     *     // handle loaded image
+     *   });
      * }
      */
-    function throttleRequestByServer(url, requestFunction) {
+    var throttleRequestByServer = function(url, requestFunction) {
         var server = getServer(url);
 
         var activeRequestsForServer = defaultValue(activeRequests[server], 0);
@@ -65,11 +66,19 @@ define([
         return when(requestFunction(url), function(result) {
             activeRequests[server]--;
             return result;
-        }, function(error) {
+        }).otherwise(function(error) {
             activeRequests[server]--;
             return when.reject(error);
         });
-    }
+    };
+
+    /**
+     * A function that will make a request if there are available slots to the server.
+     * @callback throttleRequestByServer~RequestFunction
+     *
+     * @param {String} url The url to request.
+     * @returns {Promise} A promise for the requested data.
+     */
 
     return throttleRequestByServer;
 });

Source/DynamicScene/DataSourceDisplay.js

@@ -50,8 +50,8 @@ define([
      *
      * @param {Scene} scene The scene in which to display the data.
      * @param {DataSourceCollection} dataSourceCollection The data sources to display.
-     * @param {Function} [visualizersCallback=DataSourceDisplay.defaultVisualizersCallback] A function
-     *        which takes a scene and dataSource and returns the array of visualizers used for visualization.
+     * @param {DataSourceDisplay~VisualizersCallback} [visualizersCallback=DataSourceDisplay.defaultVisualizersCallback]
+     *        A function which creates an array of visualizers used for visualization.
      *        If undefined, all standard visualizers are used.
      */
     var DataSourceDisplay = function(scene, dataSourceCollection, visualizersCallback) {
@@ -78,10 +78,11 @@ define([
     };
 
     /**
-     * Gets or sets the default function which takes a scene and dataSource and returns the
-     * array of visualizers used for visualization.  By default, this function uses all standard visualizers.
+     * Gets or sets the default function which creates an array of visualizers used for visualization.
+     * By default, this function uses all standard visualizers.
      *
-     * @type {Function}
+     * @member
+     * @type {DataSourceDisplay~VisualizersCallback}
      */
     DataSourceDisplay.defaultVisualizersCallback = function(scene, dataSource) {
         var dynamicObjects = dataSource.dynamicObjects;
@@ -211,5 +212,19 @@ define([
         }
     };
 
+    /**
+     * A function which creates an array of visualizers used for visualization.
+     * @callback DataSourceDisplay~VisualizersCallback
+     *
+     * @param {Scene} scene The scene to create visualizers for.
+     * @param {DataSource} dataSource The data source to create visualizers for.
+     * @returns {Visualizer[]} An array of visualizers used for visualization.
+     *
+     * @example
+     * function createVisualizers(scene, dataSource) {
+     *     return [new DynamicBillboardVisualizer(scene, dataSource.dynamicObjects)];
+     * }
+     */
+
     return DataSourceDisplay;
 });

Source/Scene/FrameState.js

@@ -106,7 +106,7 @@ define([
          * directly in <code>update</code> functions.
          * </p>
          *
-         * @type {Function[]}
+         * @type {FrameState~AfterRenderCallback[]}
          *
          * @example
          * frameState.afterRender.push(function() {
@@ -116,5 +116,10 @@ define([
         this.afterRender = [];
     };
 
+    /**
+     * A function that will be called at the end of the frame.
+     * @callback FrameState~AfterRenderCallback
+     */
+
     return FrameState;
 });

Source/Widgets/Animation/AnimationViewModel.js

@@ -365,11 +365,10 @@ define([
     };
 
     /**
-     * The default date formatter used by new instances.
+     * Gets or sets the default date formatter used by new instances.
      *
-     * @param {JulianDate} date The date to be formatted
-     * @param {AnimationViewModel} viewModel The AnimationViewModel instance requesting formatting.
-     * @returns {String} The string representation of the calendar date portion of the provided date.
+     * @member
+     * @type {AnimationViewModel~DateFormatter}
      */
     AnimationViewModel.defaultDateFormatter = function(date, viewModel) {
         var gregorianDate = JulianDate.toGregorianDate(date);
@@ -385,11 +384,10 @@ define([
     21600.0, 43200.0, 86400.0, 172800.0, 345600.0, 604800.0];
 
     /**
-     * The default time formatter used by new instances.
+     * Gets or sets the default time formatter used by new instances.
      *
-     * @param {JulianDate} date The date to be formatted
-     * @param {AnimationViewModel} viewModel The AnimationViewModel instance requesting formatting.
-     * @returns {String} The string representation of the time portion of the provided date.
+     * @member
+     * @type {AnimationViewModel~TimeFormatter}
      */
     AnimationViewModel.defaultTimeFormatter = function(date, viewModel) {
         var gregorianDate = JulianDate.toGregorianDate(date);
@@ -538,12 +536,11 @@ define([
         },
 
         /**
-         * Gets or sets the current date formatting function, which takes a
-         * {@link JulianDate} and an AnimationViewModel instance and
-         * returns a string representation of the calendar date portion.
+         * Gets or sets the function which formats a date for display.
          * @memberof AnimationViewModel.prototype
          *
-         * @type {Function}
+         * @type {AnimationViewModel~DateFormatter}
+         * @default AnimationViewModel.defaultDateFormatter
          */
         dateFormatter : {
             //TODO:@exception {DeveloperError} dateFormatter must be a function.
@@ -562,12 +559,11 @@ define([
         },
 
         /**
-         * Gets or sets the current time formatting function, which takes a
-         * {@link JulianDate} and an AnimationViewModel instance and
-         * returns a string representation of the time portion.
+         * Gets or sets the function which formats a time for display.
          * @memberof AnimationViewModel.prototype
          *
-         * @type {Function}
+         * @type {AnimationViewModel~TimeFormatter}
+         * @default AnimationViewModel.defaultTimeFormatter
          */
         timeFormatter : {
             //TODO:@exception {DeveloperError} timeFormatter must be a function.
@@ -590,5 +586,23 @@ define([
     AnimationViewModel._maxShuttleRingAngle = maxShuttleRingAngle;
     AnimationViewModel._realtimeShuttleRingAngle = realtimeShuttleRingAngle;
 
+    /**
+     * A function that formats a date for display.
+     * @callback AnimationViewModel~DateFormatter
+     *
+     * @param {JulianDate} date The date to be formatted
+     * @param {AnimationViewModel} viewModel The AnimationViewModel instance requesting formatting.
+     * @returns {String} The string representation of the calendar date portion of the provided date.
+     */
+
+    /**
+     * A function that formats a time for display.
+     * @callback AnimationViewModel~TimeFormatter
+     *
+     * @param {JulianDate} date The date to be formatted
+     * @param {AnimationViewModel} viewModel The AnimationViewModel instance requesting formatting.
+     * @returns {String} The string representation of the time portion of the provided date.
+     */
+
     return AnimationViewModel;
 });

Source/Workers/createTaskProcessorWorker.js

@@ -15,11 +15,10 @@ define([
      *
      * @exports createTaskProcessorWorker
      *
-     * @param {Function} workerFunction A function that takes as input two arguments:
-     * a parameters object, and an array into which transferable result objects can be pushed,
-     * and returns as output a result object.
-     * @returns {Function} An adapter function that handles the interaction with TaskProcessor,
-     * specifically, task ID management and posting a response message containing the result.
+     * @param {createTaskProcessorWorker~WorkerFunction} workerFunction The calculation function,
+     *        which takes parameters and returns a result.
+     * @returns {createTaskProcessorWorker~TaskProcessorWorkerFunction} A function that adapts the
+     *          calculation function to work as a Web Worker onmessage listener with TaskProcessor.
      *
      * @see TaskProcessor
      * @see {@link http://www.w3.org/TR/workers/|Web Workers}
@@ -87,5 +86,36 @@ define([
         };
     };
 
+    /**
+     * A function that performs a calculation in a Web Worker.
+     * @callback createTaskProcessorWorker~WorkerFunction
+     *
+     * @param {Object} parameters Parameters to the calculation.
+     * @param {Array} transferableObjects An array that should be filled with references to objects inside
+     *        the result that should be transferred back to the main document instead of copied.
+     * @returns {Object} The result of the calculation.
+     *
+     * @example
+     * function calculate(parameters, transferableObjects) {
+     *   // perform whatever calculation is necessary.
+     *   var typedArray = new Float32Array();
+     *
+     *   // typed arrays are transferable
+     *   transferableObjects.push(typedArray)
+     *
+     *   return {
+     *      typedArray : typedArray
+     *   };
+     * }
+     */
+
+    /**
+     * A Web Worker message event handler function that handles the interaction with TaskProcessor,
+     * specifically, task ID management and posting a response message containing the result.
+     * @callback createTaskProcessorWorker~TaskProcessorWorkerFunction
+     *
+     * @param {Object} event The onmessage event object.
+     */
+
     return createTaskProcessorWorker;
 });