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/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/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

@@ -500,9 +500,8 @@ HeightmapTerrainData.prototype.interpolateHeight = function (
  * @param {Number} descendantX The X coordinate within the tiling scheme of the descendant tile for which we are upsampling.
  * @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.
+ * @returns {HeightmapTerrainData|undefined} The upsampled heightmap terrain data for the descendant tile,
+ *          or undefined if the mesh is unavailable.  Note that this provider always returns synchronously.
  */
 HeightmapTerrainData.prototype.upsample = function (
   tilingScheme,

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/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

@@ -934,12 +934,13 @@ function ScreenSpaceEventHandler(element) {
   registerListeners(this);
 }
 
+// TODO: document callback signature for each type of event
 /**
  * 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 {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,8 +967,8 @@ 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.
@@ -989,8 +990,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

@@ -5,6 +5,7 @@ import Resource from "./Resource.js";
 
 /*global CESIUM_BASE_URL,define,require*/
 
+// TODO: all these should have JSDoc tags, or mark as private
 const cesiumScriptRegex = /((?:.*\/)|^)Cesium\.js(?:\?|\#|$)/;
 function getBaseUrlFromCesiumScript() {
   const scripts = document.getElementsByTagName("script");

Source/DataSources/CallbackProperty.js

@@ -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;

Source/DataSources/CompositePositionProperty.js

@@ -87,7 +87,7 @@ Object.defineProperties(CompositePositionProperty.prototype, {
  *
  * @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.
+ * @returns {Cartesian3 | undefined} The modified result parameter or a new instance if the result parameter was not supplied.
  */
 CompositePositionProperty.prototype.getValue = function (time, result) {
   return this.getValueInReferenceFrame(time, ReferenceFrame.FIXED, result);
@@ -99,7 +99,7 @@ CompositePositionProperty.prototype.getValue = function (time, result) {
  * @param {JulianDate} time The time for which to retrieve the value.
  * @param {ReferenceFrame} referenceFrame The desired referenceFrame of the result.
  * @param {Cartesian3} [result] The object to store the value into, if omitted, a new instance is created and returned.
- * @returns {Cartesian3} The modified result parameter or a new instance if the result parameter was not supplied.
+ * @returns {Cartesian3 | undefined} The modified result parameter or a new instance if the result parameter was not supplied.
  */
 CompositePositionProperty.prototype.getValueInReferenceFrame = function (
   time,

Source/DataSources/DataSource.js

@@ -58,15 +58,15 @@ Object.defineProperties(DataSource.prototype, {
   /**
    * Gets an event that will be raised if an error is encountered during processing.
    * @memberof DataSource.prototype
-   * @type {Event}
+   * @type {Event<function(this, RequestErrorEvent)>}
    */
   errorEvent: {
     get: DeveloperError.throwInstantiationError,
   },
   /**
    * Gets an event that will be raised when the value of isLoading changes.
    * @memberof DataSource.prototype
-   * @type {Event}
+   * @type {Event<function(this, boolean)>}
    */
   loadingEvent: {
     get: DeveloperError.throwInstantiationError,

Source/DataSources/EntityCluster.js

@@ -560,7 +560,7 @@ Object.defineProperties(EntityCluster.prototype, {
   /**
    * Gets the event that will be raised when a new cluster will be displayed. The signature of the event listener is {@link EntityCluster.newClusterCallback}.
    * @memberof EntityCluster.prototype
-   * @type {Event}
+   * @type {Event<EntityCluster.newClusterCallback>}
    */
   clusterEvent: {
     get: function () {
@@ -981,8 +981,11 @@ EntityCluster.prototype.destroy = function () {
  * @callback EntityCluster.newClusterCallback
  *
  * @param {Entity[]} clusteredEntities An array of the entities contained in the cluster.
- * @param {Object} cluster An object containing billboard, label, and point properties. The values are the same as
- * billboard, label and point entities, but must be the values of the ConstantProperty.
+ * @param {Object} cluster An object containing the Billboard, Label, and Point
+ * primitives that represent this cluster of entities.
+ * @param {Billboard} cluster.billboard
+ * @param {Label} cluster.label
+ * @param {PointPrimitive} cluster.point
  *
  * @example
  * // The default cluster values.

Source/DataSources/EntityCollection.js

@@ -103,22 +103,21 @@ EntityCollection.prototype.resumeEvents = function () {
 
 /**
  * The signature of the event generated by {@link EntityCollection#collectionChanged}.
- * @function
+ * @callback EntityCollection.CollectionChangedEventCallback
  *
  * @param {EntityCollection} collection The collection that triggered the event.
  * @param {Entity[]} added The array of {@link Entity} instances that have been added to the collection.
  * @param {Entity[]} removed The array of {@link Entity} instances that have been removed from the collection.
  * @param {Entity[]} changed The array of {@link Entity} instances that have been modified.
  */
-EntityCollection.collectionChangedEventCallback = undefined;
 
 Object.defineProperties(EntityCollection.prototype, {
   /**
    * Gets the event that is fired when entities are added or removed from the collection.
-   * The generated event is a {@link EntityCollection.collectionChangedEventCallback}.
+   * The generated event is a {@link EntityCollection.CollectionChangedEventCallback}.
    * @memberof EntityCollection.prototype
    * @readonly
-   * @type {Event}
+   * @type {Event<EntityCollection.CollectionChangedEventCallback>}
    */
   collectionChanged: {
     get: function () {

Source/DataSources/PositionProperty.js

@@ -63,7 +63,7 @@ Object.defineProperties(PositionProperty.prototype, {
  *
  * @param {JulianDate} time The time for which to retrieve the value.
  * @param {Cartesian3} [result] The object to store the value into, if omitted, a new instance is created and returned.
- * @returns {Cartesian3} The modified result parameter or a new instance if the result parameter was not supplied.
+ * @returns {Cartesian3 | undefined} The modified result parameter or a new instance if the result parameter was not supplied.
  */
 PositionProperty.prototype.getValue = DeveloperError.throwInstantiationError;
 
@@ -74,7 +74,7 @@ PositionProperty.prototype.getValue = DeveloperError.throwInstantiationError;
  * @param {JulianDate} time The time for which to retrieve the value.
  * @param {ReferenceFrame} referenceFrame The desired referenceFrame of the result.
  * @param {Cartesian3} [result] The object to store the value into, if omitted, a new instance is created and returned.
- * @returns {Cartesian3} The modified result parameter or a new instance if the result parameter was not supplied.
+ * @returns {Cartesian3 | undefined} The modified result parameter or a new instance if the result parameter was not supplied.
  */
 PositionProperty.prototype.getValueInReferenceFrame =
   DeveloperError.throwInstantiationError;