Merge pull request #1891 from AnalyticalGraphicsInc/documentFunctions

Documentation improvements and cleanup
CesiumGS · Jul 7, 2014 · 8486227 · 8486227
2 parents 17a35d1 + f08f491
commit 8486227
Show file tree

Hide file tree

Showing 83 changed files with 524 additions and 242 deletions.
diff --git a/Source/Core/ClockRange.js b/Source/Core/ClockRange.js
@@ -9,7 +9,8 @@ define([
      * Constants used by {@link Clock#tick} to determine behavior
      * when {@link Clock#startTime} or {@link Clock#stopTime} is reached.
      *
-     * @exports ClockRange
+     * @namespace
+     * @alias ClockRange
      *
      * @see Clock
      * @see ClockStep

diff --git a/Source/Core/ClockStep.js b/Source/Core/ClockStep.js
@@ -9,7 +9,8 @@ define([
      * Constants to determine how much time advances with each call
      * to {@link Clock#tick}.
      *
-     * @exports ClockStep
+     * @namespace
+     * @alias ClockStep
      *
      * @see Clock
      * @see ClockRange

diff --git a/Source/Core/ComponentDatatype.js b/Source/Core/ComponentDatatype.js
@@ -23,7 +23,8 @@ define([
      * WebGL component datatypes.  Components are intrinsics,
      * which form attributes, which form vertices.
      *
-     * @exports ComponentDatatype
+     * @namespace
+     * @alias ComponentDatatype
      */
     var ComponentDatatype = {
         /**

diff --git a/Source/Core/CornerType.js b/Source/Core/CornerType.js
@@ -6,13 +6,18 @@ define([
     "use strict";
 
     /**
-     * @exports CornerType
+     * Style options for corners.
+     *
+     * @namespace
+     * @alias CornerType
      */
     var CornerType = {
         /**
-         *   ___
+         * <pre>
+         *  _____
          * (  ___
          * | |
+         * </pre>
          *
          * Corner is circular.
          * @type {Number}
@@ -21,9 +26,11 @@ define([
         ROUNDED : 0,
 
         /**
+         * <pre>
          *  ______
-         * |  ___
+         * |  ____
          * | |
+         * </pre>
          *
          * Corner point is the intersection of adjacent edges.
          * @type {Number}
@@ -32,9 +39,11 @@ define([
         MITERED : 1,
 
         /**
-         *   ___
+         * <pre>
+         *  _____
          * /  ___
          * | |
+         * </pre>
          *
          * Corner is clipped.
          * @type {Number}

diff --git a/Source/Core/CorridorGeometry.js b/Source/Core/CorridorGeometry.js
@@ -634,7 +634,7 @@ define([
      * @param {Number} [options.height=0] The distance in meters between the ellipsoid surface and the positions.
      * @param {Number} [options.extrudedHeight] The distance in meters between the ellipsoid surface and the extrusion.
      * @param {VertexFormat} [options.vertexFormat=VertexFormat.DEFAULT] The vertex attributes to be computed.
-     * @param {Boolean} [options.cornerType=CornerType.ROUNDED] Determines the style of the corners.
+     * @param {CornerType} [options.cornerType=CornerType.ROUNDED] Determines the style of the corners.
      *
      * @see CorridorGeometry.createGeometry
      *

diff --git a/Source/Core/CorridorOutlineGeometry.js b/Source/Core/CorridorOutlineGeometry.js
@@ -313,7 +313,7 @@ define([
      * @param {Number} [options.granularity=CesiumMath.RADIANS_PER_DEGREE] The distance, in radians, between each latitude and longitude. Determines the number of positions in the buffer.
      * @param {Number} [options.height=0] The distance between the ellipsoid surface and the positions.
      * @param {Number} [options.extrudedHeight] The distance between the ellipsoid surface and the extrusion.
-     * @param {Boolean} [options.cornerType=CornerType.ROUNDED] Determines the style of the corners.
+     * @param {CornerType} [options.cornerType=CornerType.ROUNDED] Determines the style of the corners.
      *
      * @see CorridorOutlineGeometry.createGeometry
      *

diff --git a/Source/Core/CubicRealPolynomial.js b/Source/Core/CubicRealPolynomial.js
@@ -10,7 +10,8 @@ define([
     /**
      * Defines functions for 3rd order polynomial functions of one variable with only real coefficients.
      *
-     * @exports CubicRealPolynomial
+     * @namespace
+     * @alias CubicRealPolynomial
      */
     var CubicRealPolynomial = {};
 

diff --git a/Source/Core/EasingFunction.js b/Source/Core/EasingFunction.js
@@ -12,7 +12,8 @@ define([
      * {@link https://github.com/sole/tween.js/|Tween.js} and Robert Penner.  See the
      * {@link http://sole.github.io/tween.js/examples/03_graphs.html|Tween.js graphs for each function}.
      *
-     * @exports EasingFunction
+     * @namespace
+     * @alias EasingFunction
      *
      * @private
      */

diff --git a/Source/Core/Event.js b/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;
 });
diff --git a/Source/Core/EventHelper.js b/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;
 });
diff --git a/Source/Core/FeatureDetection.js b/Source/Core/FeatureDetection.js
@@ -115,7 +115,8 @@ define([
      * A set of functions to detect whether the current browser supports
      * various features.
      *
-     * @exports FeatureDetection
+     * @namespace
+     * @alias FeatureDetection
      */
     var FeatureDetection = {
         isChrome : isChrome,

diff --git a/Source/Core/Fullscreen.js b/Source/Core/Fullscreen.js
@@ -20,7 +20,8 @@ define([
     /**
      * Browser-independent functions for working with the standard fullscreen API.
      *
-     * @exports Fullscreen
+     * @namespace
+     * @alias Fullscreen
      *
      * @see {@link http://dvcs.w3.org/hg/fullscreen/raw-file/tip/Overview.html|W3C Fullscreen Living Specification}
      */
@@ -33,7 +34,7 @@ define([
          * @memberof Fullscreen
          * @type {Object}
          */
-        element: {
+        element : {
             get : function() {
                 if (!Fullscreen.supportsFullscreen()) {
                     return undefined;
@@ -139,7 +140,7 @@ define([
         //check for the correct combination of prefix plus the various names that browsers use
         var prefixes = ['webkit', 'moz', 'o', 'ms', 'khtml'];
         var name;
-        for ( var i = 0, len = prefixes.length; i < len; ++i) {
+        for (var i = 0, len = prefixes.length; i < len; ++i) {
             var prefix = prefixes[i];
 
             // casing of Fullscreen differs across browsers

diff --git a/Source/Core/GeometryPipeline.js b/Source/Core/GeometryPipeline.js
@@ -52,7 +52,8 @@ define([
     /**
      * Content pipeline functions for geometries.
      *
-     * @exports GeometryPipeline
+     * @namespace
+     * @alias GeometryPipeline
      *
      * @see Geometry
      */

diff --git a/Source/Core/HeightmapTessellator.js b/Source/Core/HeightmapTessellator.js
@@ -20,7 +20,8 @@ define([
     /**
      * Contains functions to create a mesh from a heightmap image.
      *
-     * @exports HeightmapTessellator
+     * @namespace
+     * @alias HeightmapTessellator
      */
     var HeightmapTessellator = {};
 
@@ -30,13 +31,13 @@ define([
      * @constant
      */
     HeightmapTessellator.DEFAULT_STRUCTURE = freezeObject({
-            heightScale : 1.0,
-            heightOffset : 0.0,
-            elementsPerHeight : 1,
-            stride : 1,
-            elementMultiplier : 256.0,
-            isBigEndian : false
-        });
+        heightScale : 1.0,
+        heightOffset : 0.0,
+        elementsPerHeight : 1,
+        stride : 1,
+        elementMultiplier : 256.0,
+        isBigEndian : false
+    });
 
     /**
      * Fills an array of vertices from a heightmap image.  On return, the vertex data is in the order
@@ -211,7 +212,7 @@ define([
             ++endCol;
         }
 
-        for ( var rowIndex = startRow; rowIndex < endRow; ++rowIndex) {
+        for (var rowIndex = startRow; rowIndex < endRow; ++rowIndex) {
             var row = rowIndex;
             if (row < 0) {
                 row = 0;
@@ -234,7 +235,7 @@ define([
 
             var v = (latitude - geographicSouth) / (geographicNorth - geographicSouth);
 
-            for ( var colIndex = startCol; colIndex < endCol; ++colIndex) {
+            for (var colIndex = startCol; colIndex < endCol; ++colIndex) {
                 var col = colIndex;
                 if (col < 0) {
                     col = 0;

diff --git a/Source/Core/HermitePolynomialApproximation.js b/Source/Core/HermitePolynomialApproximation.js
@@ -57,7 +57,9 @@ define([
 
     /**
      * An {@link InterpolationAlgorithm} for performing Hermite interpolation.
-     * @exports HermitePolynomialApproximation
+     *
+     * @namespace
+     * @alias HermitePolynomialApproximation
      */
     var HermitePolynomialApproximation = {
         type : 'Hermite'

diff --git a/Source/Core/Iau2000Orientation.js b/Source/Core/Iau2000Orientation.js
@@ -17,7 +17,9 @@ define([
      * This is a collection of the orientation information available for central bodies.
      * The data comes from the Report of the IAU/IAG Working Group on Cartographic
      * Coordinates and Rotational Elements: 2000.
-     * @exports Iau2000Orientation
+     *
+     * @namespace
+     * @alias Iau2000Orientation
      *
      * @private
      */

diff --git a/Source/Core/IauOrientationAxes.js b/Source/Core/IauOrientationAxes.js
@@ -23,13 +23,13 @@ define([
      * @alias IauOrientationAxes
      * @constructor
      *
-     * @param {Function} [computeFunction] The function that computes the {@link IauOrientationParameters} given a {@link JulianDate}.
+     * @param {IauOrientationAxes~ComputeFunction} [computeFunction] The function that computes the {@link IauOrientationParameters} given a {@link JulianDate}.
      *
      * @see Iau2000Orientation
      *
      * @private
      */
-    var IauOrientationAxes = function (computeFunction) {
+    var IauOrientationAxes = function(computeFunction) {
         if (!defined(computeFunction) || typeof computeFunction !== 'function') {
             computeFunction = Iau2000Orientation.ComputeMoon;
         }
@@ -99,5 +99,12 @@ define([
         return cbi2cbf;
     };
 
+    /**
+     * A function that computes the {@link IauOrientationParameters} for a {@link JulianDate}.
+     * @callback IauOrientationAxes~ComputeFunction
+     * @param {JulianDate} date The date to evaluate the parameters.
+     * @returns {IauOrientationParameters} The orientation parameters.
+     */
+
     return IauOrientationAxes;
 });
diff --git a/Source/Core/IauOrientationParameters.js b/Source/Core/IauOrientationParameters.js
@@ -9,7 +9,9 @@ define(function() {
      * These parameters correspond to the parameters in the Report from the IAU/IAG Working Group
      * except that they are expressed in radians.
      * </p>
-     * @exports IauOrientationParameters
+     *
+     * @namespace
+     * @alias IauOrientationParameters
      *
      * @private
      */

diff --git a/Source/Core/IndexDatatype.js b/Source/Core/IndexDatatype.js
@@ -15,7 +15,8 @@ define([
      * Constants for WebGL index datatypes.  These corresponds to the
      * <code>type</code> parameter of {@link http://www.khronos.org/opengles/sdk/docs/man/xhtml/glDrawElements.xml|drawElements}.
      *
-     * @exports IndexDatatype
+     * @namespace
+     * @alias IndexDatatype
      */
     var IndexDatatype = {
         /**

diff --git a/Source/Core/InterpolationAlgorithm.js b/Source/Core/InterpolationAlgorithm.js
@@ -7,7 +7,9 @@ define([
 
     /**
      * The interface for interpolation algorithms.
-     * @exports InterpolationAlgorithm
+     *
+     * @namespace
+     * @alias InterpolationAlgorithm
      *
      * @see LagrangePolynomialApproximation
      * @see LinearApproximation

diff --git a/Source/Core/Intersect.js b/Source/Core/Intersect.js
@@ -11,7 +11,8 @@ define([
      * partially inside the frustum and partially outside (INTERSECTING), or somwhere entirely
      * outside of the frustum's 6 planes (OUTSIDE).
      *
-     * @exports Intersect
+     * @namespace
+     * @alias Intersect
      */
     var Intersect = {
         /**

diff --git a/Source/Core/IntersectionTests.js b/Source/Core/IntersectionTests.js
@@ -22,7 +22,8 @@ define([
     /**
      * Functions for computing the intersection between geometries such as rays, planes, triangles, and ellipsoids.
      *
-     * @exports IntersectionTests
+     * @namespace
+     * @alias IntersectionTests
      */
     var IntersectionTests = {};
 

diff --git a/Source/Core/Intersections2D.js b/Source/Core/Intersections2D.js
@@ -11,7 +11,9 @@ define([
 
     /**
      * Contains functions for operating on 2D triangles.
-     * @exports Intersections2D
+     *
+     * @namespace
+     * @alias Intersections2D
      */
     var Intersections2D = {};
 

diff --git a/Source/Core/Iso8601.js b/Source/Core/Iso8601.js
@@ -19,7 +19,8 @@ define([
     /**
      * Constants related to ISO8601 support.
      *
-     * @exports Iso8601
+     * @namespace
+     * @alias Iso8601
      *
      * @see {@link http://en.wikipedia.org/wiki/ISO_8601|ISO 8601 on Wikipedia}
      * @see JulianDate