Merge pull request #8878 from CesiumGS/typescript-definitions

Generate official TypeScript type definitions

.gitignore

@@ -14,6 +14,7 @@ Thumbs.db
 /Apps/Sandcastle/templates/bucket.css
 
 /Source/Cesium.js
+/Source/Cesium.d.ts
 
 /Specs/SpecList.js
 /Source/Shaders/**/*.js

.travis.yml

@@ -12,6 +12,7 @@ script:
   - npm --silent run prettier-check
 
   - npm --silent run build
+  - npm --silent run build-ts
   - npm --silent run coverage -- --browsers FirefoxHeadless --webgl-stub --failTaskOnError --suppressPassed
 
   - travis_wait 20 npm --silent run makeZipFile -- --concurrency 1

Apps/Sandcastle/gallery/Custom Geocoder.html

@@ -56,7 +56,7 @@
          * The function called to geocode using this geocoder service.
          *
          * @param {String} input The query to be sent to the geocoder service
-         * @returns {Promise<GeocoderService~Result[]>}
+         * @returns {Promise<GeocoderService.Result[]>}
          */
         OpenStreetMapNominatimGeocoder.prototype.geocode = function (input) {
           var endpoint = "https://nominatim.openstreetmap.org/search";

CHANGES.md

@@ -2,6 +2,12 @@
 
 ### 1.70.0 - 2020-06-01
 
+##### Major Announcements :loudspeaker:
+
+- Cesium now ships with official TypeScript type definitions!
+  - If you import Cesium as a module, the new definitions will automatically be used by TypeScript and related tooling.
+  - If you import individual Cesium source files directly, you'll need to add `"types": ["cesium"]` in your tsconfig.json in order for the definitions to be used.
+
 ##### Additions :tada:
 
 - Added support for rendering the globe with translucency. [#8726](https://github.com/CesiumGS/cesium/pull/8726)

CONTRIBUTORS.md

@@ -256,3 +256,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to Cesiu
 - [SungHo Lim](https://github.com/SambaLim)
 - [Michael Fink](https://github.com/vividos)
 - [Jakub Vrana](https://github.com/vrana)
+- [James Bromwell](https://github.com/thw0rted)

Documentation/Contributors/DocumentationGuide/README.md

@@ -25,6 +25,7 @@ Generally, just follow the patterns that are already in comparable parts of the
   - [Property](#property)
   - [Property Getter/Setter](#property-gettersetter)
   - [Standalone Function](#standalone-function)
+- [TypeScript type definitions](#typescript)
 
 ## Building the Doc
 
@@ -52,7 +53,7 @@ Consider one of the simplest functions in CesiumJS, `defined`:
 
 ```javascript
 /**
- * @exports defined
+ * @function
  *
  * @param {*} value The object.
  * @returns {Boolean} Returns true if the object is defined, returns false otherwise.
@@ -70,7 +71,7 @@ function defined(value) {
 ```
 
 - The doc for `defined` is in the comment starting with `/**`. JSDoc tags begin with `@`.
-- `@exports` describes the name of the function that is exported from the module.
+- `@function` tells JSDoc that this is a function.
 - `@param` describes the function's parameters, and `@returns` describes the function's return value.
 - `@example` describes a code sample.
 
@@ -379,7 +380,7 @@ Cartesian4.fromArray = Cartesian4.unpack;
 /**
  * Sort the items in the queue in-place.
  *
- * @param {Queue~Comparator} 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) {
@@ -393,7 +394,7 @@ Queue.prototype.sort = function (compareFunction) {
 
 /**
  * A function used to compare two items while sorting a queue.
- * @callback Queue~Comparator
+ * @callback Queue.Comparator
  *
  * @param {*} a An item in the array.
  * @param {*} b An item in the array.
@@ -535,7 +536,7 @@ DESCRIPTION.
 ```
 DESCRIPTION.
 
-@exports NAME
+@function
 
 @param {TYPE} NAME DESCRIPTION.
 @param {TYPE|OTHER_TYPE} NAME DESCRIPTION WITH LONG
@@ -552,3 +553,13 @@ DESCRIPTION.
 
 [@private]
 ```
+
+# TypeScript
+
+We also use JSDoc to build official TypeScript type definitions. Normally this behavior is transparent to the developer and happens as part of CI, however incorrect or non-standard JSDoc can lead to failures. If CI is failing because of the `build-ts` step, you can debug it locally by running:
+
+```
+npm run build-ts
+```
+
+In most cases, the TypeScript compiler will provide a very obvious error and line number which will help you track down the offending, most likely incorrect, JSDoc.

Source/Core/ApproximateTerrainHeights.js

@@ -36,7 +36,7 @@ var ApproximateTerrainHeights = {};
 
 /**
  * Initializes the minimum and maximum terrain heights
- * @return {Promise}
+ * @return {Promise<void>}
  */
 ApproximateTerrainHeights.initialize = function () {
   var initPromise = ApproximateTerrainHeights._initPromise;

Source/Core/ArcGISTiledElevationTerrainProvider.js

@@ -294,6 +294,19 @@ Object.defineProperties(ArcGISTiledElevationTerrainProvider.prototype, {
       return false;
     },
   },
+  /**
+   * Gets an object that can be used to determine availability of terrain from this provider, such as
+   * at points and in rectangles.  This function should not be called before
+   * {@link TerrainProvider#ready} returns true.  This property may be undefined if availability
+   * information is not available.
+   * @memberof ArcGISTiledElevationTerrainProvider.prototype
+   * @type {TileAvailability}
+   */
+  availability: {
+    get: function () {
+      return undefined;
+    },
+  },
 });
 
 /**
@@ -459,7 +472,7 @@ ArcGISTiledElevationTerrainProvider.prototype.getTileDataAvailable = function (
  * @param {Number} x The X coordinate of the tile for which to request geometry.
  * @param {Number} y The Y coordinate of the tile for which to request geometry.
  * @param {Number} level The level of the tile for which to request geometry.
- * @returns {undefined|Promise} Undefined if nothing need to be loaded or a Promise that resolves when all required tiles are loaded
+ * @returns {undefined|Promise<void>} Undefined if nothing need to be loaded or a Promise that resolves when all required tiles are loaded
  */
 ArcGISTiledElevationTerrainProvider.prototype.loadTileDataAvailability = function (
   x,

Source/Core/ArcType.js

@@ -1,7 +1,7 @@
 /**
  * ArcType defines the path that should be taken connecting vertices.
  *
- * @exports ArcType
+ * @enum {Number}
  */
 var ArcType = {
   /**

Source/Core/AttributeCompression.js

@@ -11,7 +11,7 @@ var LEFT_SHIFT = 256.0;
 /**
  * Attribute compression and decompression functions.
  *
- * @exports AttributeCompression
+ * @namespace AttributeCompression
  *
  * @private
  */

Source/Core/BingMapsApi.js

@@ -7,7 +7,7 @@ import defined from "./defined.js";
  * or {@link BingMapsGeocoderService}. You can create your own key at
  * {@link https://www.bingmapsportal.com/}.
  *
- * @exports BingMapsApi
+ * @namespace BingMapsApi
  */
 var BingMapsApi = {};
 
@@ -19,6 +19,12 @@ var BingMapsApi = {};
  */
 BingMapsApi.defaultKey = undefined;
 
+/**
+ * Gets the key to use to access the Bing Maps API. If the provided
+ * key is defined, it is returned. Otherwise, returns {@link BingMapsApi.defaultKey}.
+ * @param {string|null|undefined} providedKey The provided key to use if defined.
+ * @returns {string|undefined} The Bing Maps API key to use.
+ */
 BingMapsApi.getKey = function (providedKey) {
   if (defined(providedKey)) {
     return providedKey;

Source/Core/BingMapsGeocoderService.js

@@ -58,7 +58,7 @@ Object.defineProperties(BingMapsGeocoderService.prototype, {
  * @function
  *
  * @param {String} query The query to be sent to the geocoder service
- * @returns {Promise<GeocoderService~Result[]>}
+ * @returns {Promise<GeocoderService.Result[]>}
  */
 BingMapsGeocoderService.prototype.geocode = function (query) {
   //>>includeStart('debug', pragmas.debug);

Source/Core/Cartesian2.js

@@ -665,7 +665,7 @@ Cartesian2.equalsArray = function (cartesian, array, offset) {
  *
  * @param {Cartesian2} [left] The first Cartesian.
  * @param {Cartesian2} [right] The second Cartesian.
- * @param {Number} relativeEpsilon The relative epsilon tolerance to use for equality testing.
+ * @param {Number} [relativeEpsilon=0] The relative epsilon tolerance to use for equality testing.
  * @param {Number} [absoluteEpsilon=relativeEpsilon] The absolute epsilon tolerance to use for equality testing.
  * @returns {Boolean} <code>true</code> if left and right are within the provided epsilon, <code>false</code> otherwise.
  */
@@ -745,7 +745,7 @@ Cartesian2.prototype.equals = function (right) {
  * <code>false</code> otherwise.
  *
  * @param {Cartesian2} [right] The right hand side Cartesian.
- * @param {Number} relativeEpsilon The relative epsilon tolerance to use for equality testing.
+ * @param {Number} [relativeEpsilon=0] The relative epsilon tolerance to use for equality testing.
  * @param {Number} [absoluteEpsilon=relativeEpsilon] The absolute epsilon tolerance to use for equality testing.
  * @returns {Boolean} <code>true</code> if they are within the provided epsilon, <code>false</code> otherwise.
  */

Source/Core/Cartesian3.js

@@ -742,7 +742,7 @@ Cartesian3.equalsArray = function (cartesian, array, offset) {
  *
  * @param {Cartesian3} [left] The first Cartesian.
  * @param {Cartesian3} [right] The second Cartesian.
- * @param {Number} relativeEpsilon The relative epsilon tolerance to use for equality testing.
+ * @param {Number} [relativeEpsilon=0] The relative epsilon tolerance to use for equality testing.
  * @param {Number} [absoluteEpsilon=relativeEpsilon] The absolute epsilon tolerance to use for equality testing.
  * @returns {Boolean} <code>true</code> if left and right are within the provided epsilon, <code>false</code> otherwise.
  */
@@ -1152,7 +1152,7 @@ Cartesian3.prototype.equals = function (right) {
  * <code>false</code> otherwise.
  *
  * @param {Cartesian3} [right] The right hand side Cartesian.
- * @param {Number} relativeEpsilon The relative epsilon tolerance to use for equality testing.
+ * @param {Number} [relativeEpsilon=0] The relative epsilon tolerance to use for equality testing.
  * @param {Number} [absoluteEpsilon=relativeEpsilon] The absolute epsilon tolerance to use for equality testing.
  * @returns {Boolean} <code>true</code> if they are within the provided epsilon, <code>false</code> otherwise.
  */

Source/Core/Cartesian4.js

@@ -735,7 +735,7 @@ Cartesian4.equalsArray = function (cartesian, array, offset) {
  *
  * @param {Cartesian4} [left] The first Cartesian.
  * @param {Cartesian4} [right] The second Cartesian.
- * @param {Number} relativeEpsilon The relative epsilon tolerance to use for equality testing.
+ * @param {Number} [relativeEpsilon=0] The relative epsilon tolerance to use for equality testing.
  * @param {Number} [absoluteEpsilon=relativeEpsilon] The absolute epsilon tolerance to use for equality testing.
  * @returns {Boolean} <code>true</code> if left and right are within the provided epsilon, <code>false</code> otherwise.
  */
@@ -843,7 +843,7 @@ Cartesian4.prototype.equals = function (right) {
  * <code>false</code> otherwise.
  *
  * @param {Cartesian4} [right] The right hand side Cartesian.
- * @param {Number} relativeEpsilon The relative epsilon tolerance to use for equality testing.
+ * @param {Number} [relativeEpsilon=0] The relative epsilon tolerance to use for equality testing.
  * @param {Number} [absoluteEpsilon=relativeEpsilon] The absolute epsilon tolerance to use for equality testing.
  * @returns {Boolean} <code>true</code> if they are within the provided epsilon, <code>false</code> otherwise.
  */

Source/Core/Cartographic.js

@@ -233,13 +233,11 @@ Cartographic.equals = function (left, right) {
  *
  * @param {Cartographic} [left] The first cartographic.
  * @param {Cartographic} [right] The second cartographic.
- * @param {Number} epsilon The epsilon to use for equality testing.
+ * @param {Number} [epsilon=0] The epsilon to use for equality testing.
  * @returns {Boolean} <code>true</code> if left and right are within the provided epsilon, <code>false</code> otherwise.
  */
 Cartographic.equalsEpsilon = function (left, right, epsilon) {
-  //>>includeStart('debug', pragmas.debug);
-  Check.typeOf.number("epsilon", epsilon);
-  //>>includeEnd('debug');
+  epsilon = defaultValue(epsilon, 0);
 
   return (
     left === right ||
@@ -286,7 +284,7 @@ Cartographic.prototype.equals = function (right) {
  * <code>false</code> otherwise.
  *
  * @param {Cartographic} [right] The second cartographic.
- * @param {Number} epsilon The epsilon to use for equality testing.
+ * @param {Number} [epsilon=0] The epsilon to use for equality testing.
  * @returns {Boolean} <code>true</code> if left and right are within the provided epsilon, <code>false</code> otherwise.
  */
 Cartographic.prototype.equalsEpsilon = function (right, epsilon) {

Source/Core/CartographicGeocoderService.js

@@ -15,7 +15,7 @@ function CartographicGeocoderService() {}
  * @function
  *
  * @param {String} query The query to be sent to the geocoder service
- * @returns {Promise<GeocoderService~Result[]>}
+ * @returns {Promise<GeocoderService.Result[]>}
  */
 CartographicGeocoderService.prototype.geocode = function (query) {
   //>>includeStart('debug', pragmas.debug);

Source/Core/CesiumTerrainProvider.js

@@ -485,7 +485,7 @@ function CesiumTerrainProvider(options) {
  * When using the Quantized-Mesh format, a tile may be returned that includes additional extensions, such as PerVertexNormals, watermask, etc.
  * This enumeration defines the unique identifiers for each type of extension data that has been appended to the standard mesh data.
  *
- * @exports QuantizedMeshExtensionIds
+ * @namespace QuantizedMeshExtensionIds
  * @see CesiumTerrainProvider
  * @private
  */
@@ -1201,7 +1201,7 @@ CesiumTerrainProvider.prototype.getTileDataAvailable = function (x, y, level) {
  * @param {Number} x The X coordinate of the tile for which to request geometry.
  * @param {Number} y The Y coordinate of the tile for which to request geometry.
  * @param {Number} level The level of the tile for which to request geometry.
- * @returns {undefined|Promise} Undefined if nothing need to be loaded or a Promise that resolves when all required tiles are loaded
+ * @returns {undefined|Promise<void>} Undefined if nothing need to be loaded or a Promise that resolves when all required tiles are loaded
  */
 CesiumTerrainProvider.prototype.loadTileDataAvailability = function (
   x,

Source/Core/ClockRange.js

@@ -2,7 +2,7 @@
  * Constants used by {@link Clock#tick} to determine behavior
  * when {@link Clock#startTime} or {@link Clock#stopTime} is reached.
  *
- * @exports ClockRange
+ * @enum {Number}
  *
  * @see Clock
  * @see ClockStep

Source/Core/ClockStep.js

@@ -2,7 +2,7 @@
  * Constants to determine how much time advances with each call
  * to {@link Clock#tick}.
  *
- * @exports ClockStep
+ * @enum {Number}
  *
  * @see Clock
  * @see ClockRange

Source/Core/ComponentDatatype.js

@@ -7,7 +7,7 @@ import WebGLConstants from "./WebGLConstants.js";
  * WebGL component datatypes.  Components are intrinsics,
  * which form attributes, which form vertices.
  *
- * @exports ComponentDatatype
+ * @enum {Number}
  */
 var ComponentDatatype = {
   /**
@@ -137,7 +137,7 @@ ComponentDatatype.getSizeInBytes = function (componentDatatype) {
 /**
  * Gets the {@link ComponentDatatype} for the provided TypedArray instance.
  *
- * @param {TypedArray} array The typed array.
+ * @param {Int8Array|Uint8Array|Int16Array|Uint16Array|Int32Array|Uint32Array|Float32Array|Float64Array} array The typed array.
  * @returns {ComponentDatatype} The ComponentDatatype for the provided array, or undefined if the array is not a TypedArray.
  */
 ComponentDatatype.fromTypedArray = function (array) {

Source/Core/CornerType.js

@@ -4,7 +4,7 @@
  * @demo The {@link https://sandcastle.cesium.com/index.html?src=Corridor.html&label=Geometries|Corridor Demo}
  * demonstrates the three corner types, as used by {@link CorridorGraphics}.
  *
- * @exports CornerType
+ * @enum {Number}
  */
 var CornerType = {
   /**

Source/Core/CubicRealPolynomial.js

@@ -4,7 +4,7 @@ import QuadraticRealPolynomial from "./QuadraticRealPolynomial.js";
 /**
  * Defines functions for 3rd order polynomial functions of one variable with only real coefficients.
  *
- * @exports CubicRealPolynomial
+ * @namespace CubicRealPolynomial
  */
 var CubicRealPolynomial = {};