TypeScript fixes again

CHANGES.md

@@ -12,6 +12,7 @@
 ##### Fixes :wrench:
 
 - Fixed `GoogleEarthEnterpriseImageryProvider.requestImagery`, `GridImageryProvider.requestImagery`, and `TileCoordinateImageryProvider.requestImagery` return types to match interface. [#10265](https://github.com/CesiumGS/cesium/issues/10265)
+- Various property and return type definitions were corrected, and the `Event` class was made generic in order to support strongly typed event callbacks. [#10292](https://github.com/CesiumGS/cesium/pull/10292)
 - Fixed debug label rendering in `Cesium3dTilesInspector`. [#10246](https://github.com/CesiumGS/cesium/issues/10246)
 
 ### 1.92 - 2022-04-01

Source/Core/ApproximateTerrainHeights.js

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

Source/Core/ArcGISTiledElevationTerrainProvider.js

@@ -488,7 +488,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<void>} Undefined if nothing need to be loaded or a Promise that resolves when all required tiles are loaded
+ * @returns {undefined} This provider does not support loading availability.
  */
 ArcGISTiledElevationTerrainProvider.prototype.loadTileDataAvailability = function (
   x,

Source/Core/EllipsoidTerrainProvider.js

@@ -218,7 +218,7 @@ EllipsoidTerrainProvider.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<void>} Undefined if nothing need to be loaded or a Promise that resolves when all required tiles are loaded
+ * @returns {undefined} This provider does not support loading availability.
  */
 EllipsoidTerrainProvider.prototype.loadTileDataAvailability = function (
   x,

Source/Core/Event.js

@@ -7,6 +7,7 @@ import defined from "./defined.js";
  * exposed as a property for others to subscribe to.
  *
  * @alias Event
+ * @template Listener extends (...args: any[]) => void = (...args: any[]) => void
  * @constructor
  * @example
  * MyObject.prototype.myListener = function(arg1, arg2) {
@@ -46,7 +47,7 @@ Object.defineProperties(Event.prototype, {
  * An optional scope can be provided to serve as the <code>this</code> pointer
  * in which the function will execute.
  *
- * @param {Function} listener The function to be executed when the event is raised.
+ * @param {Listener} 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 {Event.RemoveCallback} A function that will remove this event listener when invoked.
@@ -71,7 +72,7 @@ Event.prototype.addEventListener = function (listener, scope) {
 /**
  * Unregisters a previously registered callback.
  *
- * @param {Function} listener The function to be unregistered.
+ * @param {Listener} listener The function to be unregistered.
  * @param {Object} [scope] The scope that was originally passed to addEventListener.
  * @returns {Boolean} <code>true</code> if the listener was removed; <code>false</code> if the listener and scope are not registered with the event.
  *
@@ -119,7 +120,7 @@ function compareNumber(a, b) {
 /**
  * Raises the event by calling each registered listener with all supplied arguments.
  *
- * @param {...Object} arguments This method takes any number of parameters and passes them through to the listener functions.
+ * @param {...Parameters<Listener>} arguments This method takes any number of parameters and passes them through to the listener functions.
  *
  * @see Event#addEventListener
  * @see Event#removeEventListener
@@ -159,4 +160,5 @@ Event.prototype.raiseEvent = function () {
  * A function that removes a listener.
  * @callback Event.RemoveCallback
  */
+
 export default Event;

Source/Core/ExperimentalFeatures.js

@@ -13,6 +13,7 @@
  *   <li>To avoid cluttering the code, check the flag in as few places as possible. Ideally this would be a single place.</li>
  * </ul>
  *
+ * @namespace
  * @experimental This feature is using part of the 3D Tiles spec that is not final and is subject to change without Cesium's standard deprecation policy.
  */
 const ExperimentalFeatures = {

Source/Core/GoogleEarthEnterpriseTerrainProvider.js

@@ -618,7 +618,7 @@ GoogleEarthEnterpriseTerrainProvider.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<void>} Undefined if nothing need to be loaded or a Promise that resolves when all required tiles are loaded
+ * @returns {undefined}
  */
 GoogleEarthEnterpriseTerrainProvider.prototype.loadTileDataAvailability = function (
   x,

Source/Core/HeightmapTerrainData.js

@@ -501,8 +501,7 @@ HeightmapTerrainData.prototype.interpolateHeight = function (
  * @param {Number} descendantY The Y coordinate within the tiling scheme of the descendant tile for which we are upsampling.
  * @param {Number} descendantLevel The level within the tiling scheme of the descendant tile for which we are upsampling.
  * @returns {Promise.<HeightmapTerrainData>|undefined} A promise for upsampled heightmap terrain data for the descendant tile,
- *          or undefined if too many asynchronous upsample operations are in progress and the request has been
- *          deferred.
+ *          or undefined if the mesh is unavailable.
  */
 HeightmapTerrainData.prototype.upsample = function (
   tilingScheme,
@@ -627,14 +626,16 @@ HeightmapTerrainData.prototype.upsample = function (
     }
   }
 
-  return new HeightmapTerrainData({
-    buffer: heights,
-    width: width,
-    height: height,
-    childTileMask: 0,
-    structure: this._structure,
-    createdByUpsampling: true,
-  });
+  return Promise.resolve(
+    new HeightmapTerrainData({
+      buffer: heights,
+      width: width,
+      height: height,
+      childTileMask: 0,
+      structure: this._structure,
+      createdByUpsampling: true,
+    })
+  );
 };
 
 /**

Source/Core/Iso8601.js

@@ -46,7 +46,7 @@ const Iso8601 = {
    * A {@link TimeInterval} representing the largest interval representable by an ISO8601 interval.
    * This is equivalent to the interval string '0000-01-01T00:00:00Z/9999-12-31T24:00:00Z'
    *
-   * @type {JulianDate}
+   * @type {TimeInterval}
    * @constant
    */
   MAXIMUM_INTERVAL: MAXIMUM_INTERVAL,

Source/Core/Matrix2.js

@@ -176,6 +176,7 @@ Matrix2.clone = function (matrix, result) {
 /**
  * Creates a Matrix2 from 4 consecutive elements in an array.
  *
+ * @function
  * @param {Number[]} array The array whose 4 consecutive elements correspond to the positions of the matrix.  Assumes column-major order.
  * @param {Number} [startingIndex=0] The offset into the array of the first element, which corresponds to first column first row position in the matrix.
  * @param {Matrix2} [result] The object onto which to store the result.

Source/Core/Matrix3.js

@@ -227,6 +227,7 @@ Matrix3.clone = function (matrix, result) {
 /**
  * Creates a Matrix3 from 9 consecutive elements in an array.
  *
+ * @function
  * @param {Number[]} array The array whose 9 consecutive elements correspond to the positions of the matrix.  Assumes column-major order.
  * @param {Number} [startingIndex=0] The offset into the array of the first element, which corresponds to first column first row position in the matrix.
  * @param {Matrix3} [result] The object onto which to store the result.

Source/Core/Resource.js

@@ -214,21 +214,28 @@ function combineQueryParameters(q1, q2, preserveQueryParameters) {
   return result;
 }
 
+/**
+ * @typedef {Object} Resource.ConstructorOptions
+ *
+ * Initialization options for the Resource constructor
+ *
+ * @property {String} url The url of the resource.
+ * @property {Object} [queryParameters] An object containing query parameters that will be sent when retrieving the resource.
+ * @property {Object} [templateValues] Key/Value pairs that are used to replace template values (eg. {x}).
+ * @property {Object} [headers={}] Additional HTTP headers that will be sent.
+ * @property {Proxy} [proxy] A proxy to be used when loading the resource.
+ * @property {Resource.RetryCallback} [retryCallback] The Function to call when a request for this resource fails. If it returns true, the request will be retried.
+ * @property {Number} [retryAttempts=0] The number of times the retryCallback should be called before giving up.
+ * @property {Request} [request] A Request object that will be used. Intended for internal use only.
+ */
+
 /**
  * A resource that includes the location and any other parameters we need to retrieve it or create derived resources. It also provides the ability to retry requests.
  *
  * @alias Resource
  * @constructor
  *
- * @param {String|Object} options A url or an object with the following properties
- * @param {String} options.url The url of the resource.
- * @param {Object} [options.queryParameters] An object containing query parameters that will be sent when retrieving the resource.
- * @param {Object} [options.templateValues] Key/Value pairs that are used to replace template values (eg. {x}).
- * @param {Object} [options.headers={}] Additional HTTP headers that will be sent.
- * @param {Proxy} [options.proxy] A proxy to be used when loading the resource.
- * @param {Resource.RetryCallback} [options.retryCallback] The Function to call when a request for this resource fails. If it returns true, the request will be retried.
- * @param {Number} [options.retryAttempts=0] The number of times the retryCallback should be called before giving up.
- * @param {Request} [options.request] A Request object that will be used. Intended for internal use only.
+ * @param {String|Resource.ConstructorOptions} options A url or an object describing initialization options
  *
  * @example
  * function refreshTokenRetryCallback(resource, error) {
@@ -880,7 +887,7 @@ Resource.fetchBlob = function (options) {
  * @param {Boolean} [options.preferImageBitmap=false] If true, image will be decoded during fetch and an <code>ImageBitmap</code> is returned.
  * @param {Boolean} [options.flipY=false] If true, image will be vertically flipped during decode. Only applies if the browser supports <code>createImageBitmap</code>.
  * @param {Boolean} [options.skipColorSpaceConversion=false] If true, any custom gamma or color profiles in the image will be ignored. Only applies if the browser supports <code>createImageBitmap</code>.
- * @returns {Promise.<ImageBitmap>|Promise.<HTMLImageElement>|undefined} a promise that will resolve to the requested data when loaded. Returns undefined if <code>request.throttle</code> is true and the request does not have high enough priority.
+ * @returns {Promise.<ImageBitmap|HTMLImageElement>|undefined} a promise that will resolve to the requested data when loaded. Returns undefined if <code>request.throttle</code> is true and the request does not have high enough priority.
  *
  *
  * @example
@@ -1082,7 +1089,7 @@ function fetchImage(options) {
  * @param {Boolean} [options.preferBlob=false]  If true, we will load the image via a blob.
  * @param {Boolean} [options.preferImageBitmap=false] If true, image will be decoded during fetch and an <code>ImageBitmap</code> is returned.
  * @param {Boolean} [options.skipColorSpaceConversion=false] If true, any custom gamma or color profiles in the image will be ignored. Only applies when requesting an image and the browser supports <code>createImageBitmap</code>.
- * @returns {Promise.<ImageBitmap>|Promise.<HTMLImageElement>|undefined} a promise that will resolve to the requested data when loaded. Returns undefined if <code>request.throttle</code> is true and the request does not have high enough priority.
+ * @returns {Promise.<ImageBitmap|HTMLImageElement>|undefined} a promise that will resolve to the requested data when loaded. Returns undefined if <code>request.throttle</code> is true and the request does not have high enough priority.
  */
 Resource.fetchImage = function (options) {
   const resource = new Resource(options);

Source/Core/ScreenSpaceEventHandler.js

@@ -892,6 +892,83 @@ function handlePointerMove(screenSpaceEventHandler, event) {
   }
 }
 
+/**
+ * @typedef {Object} ScreenSpaceEventHandler.PositionedEvent
+ *
+ * An Event that occurs at a single position on screen.
+ *
+ * @property {Cartesian2} position
+ */
+
+/**
+ * @callback ScreenSpaceEventHandler.PositionedEventCallback
+ *
+ * The callback invoked when a positioned event triggers an event listener.
+ *
+ * @param {ScreenSpaceEventHandler.PositionedEvent} event The event which triggered the listener
+ */
+
+/**
+ * @typedef {Object} ScreenSpaceEventHandler.MotionEvent
+ *
+ * An Event that starts at one position and ends at another.
+ *
+ * @property {Cartesian2} startPosition
+ * @property {Cartesian2} endPosition
+ */
+
+/**
+ * @callback ScreenSpaceEventHandler.MotionEventCallback
+ *
+ * The callback invoked when a motion event triggers an event listener.
+ *
+ * @param {ScreenSpaceEventHandler.MotionEvent} event The event which triggered the listener
+ */
+
+/**
+ * @typedef {Object} ScreenSpaceEventHandler.TwoPointEvent
+ *
+ * An Event that occurs at a two positions on screen.
+ *
+ * @property {Cartesian2} position1
+ * @property {Cartesian2} position2
+ */
+
+/**
+ * @callback ScreenSpaceEventHandler.TwoPointEventCallback
+ *
+ * The callback invoked when a two-point event triggers an event listener.
+ *
+ * @param {ScreenSpaceEventHandler.TwoPointEvent} event The event which triggered the listener
+ */
+
+/**
+ * @typedef {Object} ScreenSpaceEventHandler.TwoPointMotionEvent
+ *
+ * An Event that starts at a two positions on screen and moves to two other positions.
+ *
+ * @property {Cartesian2} position1
+ * @property {Cartesian2} position2
+ * @property {Cartesian2} previousPosition1
+ * @property {Cartesian2} previousPosition2
+ */
+
+/**
+ * @callback ScreenSpaceEventHandler.TwoPointMotionEventCallback
+ *
+ * The callback invoked when a two-point motion event triggers an event listener.
+ *
+ * @param {ScreenSpaceEventHandler.TwoPointMotionEvent} event The event which triggered the listener
+ */
+
+/**
+ * @callback ScreenSpaceEventHandler.WheelEventCallback
+ *
+ * The callback invoked when a mouse-wheel event triggers an event listener.
+ *
+ * @param {number} delta The amount that the mouse wheel moved
+ */
+
 /**
  * Handles user input events. Custom functions can be added to be executed on
  * when the user enters input.
@@ -937,9 +1014,9 @@ function ScreenSpaceEventHandler(element) {
 /**
  * Set a function to be executed on an input event.
  *
- * @param {Function} action Function to be executed when the input event occurs.
- * @param {Number} type The ScreenSpaceEventType of input event.
- * @param {Number} [modifier] A KeyboardEventModifier key that is held when a <code>type</code>
+ * @param {ScreenSpaceEventHandler.PositionedEventCallback|ScreenSpaceEventHandler.MotionEventCallback|ScreenSpaceEventHandler.WheelEventCallback|ScreenSpaceEventHandler.TwoPointEventCallback|ScreenSpaceEventHandler.TwoPointMotionEventCallback} action Function to be executed when the input event occurs.
+ * @param {ScreenSpaceEventType} type The ScreenSpaceEventType of input event.
+ * @param {KeyboardEventModifier} [modifier] A KeyboardEventModifier key that is held when a <code>type</code>
  * event occurs.
  *
  * @see ScreenSpaceEventHandler#getInputAction
@@ -966,11 +1043,11 @@ ScreenSpaceEventHandler.prototype.setInputAction = function (
 /**
  * Returns the function to be executed on an input event.
  *
- * @param {Number} type The ScreenSpaceEventType of input event.
- * @param {Number} [modifier] A KeyboardEventModifier key that is held when a <code>type</code>
+ * @param {ScreenSpaceEventType} type The ScreenSpaceEventType of input event.
+ * @param {KeyboardEventModifier} [modifier] A KeyboardEventModifier key that is held when a <code>type</code>
  * event occurs.
  *
- * @returns {Function} The function to be executed on an input event.
+ * @returns {ScreenSpaceEventHandler.PositionedEventCallback|ScreenSpaceEventHandler.MotionEventCallback|ScreenSpaceEventHandler.WheelEventCallback|ScreenSpaceEventHandler.TwoPointEventCallback|ScreenSpaceEventHandler.TwoPointMotionEventCallback} The function to be executed on an input event.
  *
  * @see ScreenSpaceEventHandler#setInputAction
  * @see ScreenSpaceEventHandler#removeInputAction
@@ -989,8 +1066,8 @@ ScreenSpaceEventHandler.prototype.getInputAction = function (type, modifier) {
 /**
  * Removes the function to be executed on an input event.
  *
- * @param {Number} type The ScreenSpaceEventType of input event.
- * @param {Number} [modifier] A KeyboardEventModifier key that is held when a <code>type</code>
+ * @param {ScreenSpaceEventType} type The ScreenSpaceEventType of input event.
+ * @param {KeyboardEventModifier} [modifier] A KeyboardEventModifier key that is held when a <code>type</code>
  * event occurs.
  *
  * @see ScreenSpaceEventHandler#getInputAction

Source/Core/TerrainProvider.js

@@ -26,7 +26,7 @@ Object.defineProperties(TerrainProvider.prototype, {
    * to the event, you will be notified of the error and can potentially recover from it.  Event listeners
    * are passed an instance of {@link TileProviderError}.
    * @memberof TerrainProvider.prototype
-   * @type {Event}
+   * @type {Event<TerrainProvider.ErrorEvent>}
    * @readonly
    */
   errorEvent: {
@@ -451,3 +451,11 @@ TerrainProvider.prototype.getTileDataAvailable =
 TerrainProvider.prototype.loadTileDataAvailability =
   DeveloperError.throwInstantiationError;
 export default TerrainProvider;
+
+/**
+ * A function that is called when an error occurs.
+ * @callback TerrainProvider.ErrorEvent
+ *
+ * @this TerrainProvider
+ * @param {TileProviderError} err An object holding details about the error that occurred.
+ */

Source/Core/buildModuleUrl.js

@@ -142,6 +142,9 @@ buildModuleUrl.setBaseUrl = function (value) {
 
 /**
  * Gets the base URL for resolving modules.
+ *
+ * @function
+ * @returns {String} The configured base URL
  */
 buildModuleUrl.getCesiumBaseUrl = getCesiumBaseUrl;
 

Source/DataSources/CallbackProperty.js

@@ -49,7 +49,7 @@ Object.defineProperties(CallbackProperty.prototype, {
 /**
  * Gets the value of the property.
  *
- * @param {JulianDate} [time] The time for which to retrieve the value.  This parameter is unused since the value does not change with respect to time.
+ * @param {JulianDate} time The time for which to retrieve the value.
  * @param {Object} [result] The object to store the value into, if omitted, a new instance is created and returned.
  * @returns {Object} The modified result parameter or a new instance if the result parameter was not supplied or is unsupported.
  */
@@ -104,8 +104,8 @@ CallbackProperty.prototype.equals = function (other) {
  * A function that returns the value of the property.
  * @callback CallbackProperty.Callback
  *
- * @param {JulianDate} [time] The time for which to retrieve the value.
- * @param {Object} [result] The object to store the value into, if omitted, a new instance is created and returned.
- * @returns {Object} The modified result parameter or a new instance if the result parameter was not supplied or is unsupported.
+ * @param {JulianDate} time The time for which to retrieve the value.
+ * @param {Object} [result] The object to store the value into. If omitted, the function must create and return a new instance.
+ * @returns {Object} The modified result parameter, or a new instance if the result parameter was not supplied or is unsupported.
  */
 export default CallbackProperty;