Merge pull request #12193 from CesiumGS/ts-types-allow-undefined

Updates to typedefs and documentation defaults
CesiumGS · Sep 17, 2024 · 8b4a16b · 8b4a16b
2 parents 165e0fb + 244565c
commit 8b4a16b
Show file tree

Hide file tree

Showing 12 changed files with 31 additions and 42 deletions.
diff --git a/CHANGES.md b/CHANGES.md
@@ -12,6 +12,7 @@
 ##### Fixes :wrench:
 
 - Use first geometryBuffer if no best match found in I3SNode [#12132](https://github.com/CesiumGS/cesium/pull/12132)
+- Update type definitions to allow undefined for optional parameters [#12193](https://github.com/CesiumGS/cesium/pull/12193)
 
 ### 1.121.1 - 2024-09-04
 

diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md
@@ -167,6 +167,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to Cesiu
   - [jjspace](https://github.com/jjspace)
   - [Siddhesh Ranade](https://github.com/siddheshranade)
   - [Adam Morris](https://github.com/weegeekps)
+  - [Luke McKinstry](https://github.com/lukemckinstry)
 - [Northrop Grumman](http://www.northropgrumman.com)
   - [Joseph Stein](https://github.com/nahgrin)
 - [EOX IT Services GmbH](https://eox.at)

diff --git a/packages/engine/Source/Core/Geometry.js b/packages/engine/Source/Core/Geometry.js
@@ -104,8 +104,6 @@ function Geometry(options) {
    *
    * @type GeometryAttributes
    *
-   * @default undefined
-   *
    *
    * @example
    * geometry.attributes.position = new Cesium.GeometryAttribute({
@@ -123,7 +121,7 @@ function Geometry(options) {
    * Optional index data that - along with {@link Geometry#primitiveType} -
    * determines the primitives in the geometry.
    *
-   * @type {Array}
+   * @type {Array|undefined}
    *
    * @default undefined
    */
@@ -133,9 +131,9 @@ function Geometry(options) {
    * The type of primitives in the geometry.  This is most often {@link PrimitiveType.TRIANGLES},
    * but can varying based on the specific geometry.
    *
-   * @type PrimitiveType
+   * @type {PrimitiveType|undefined}
    *
-   * @default undefined
+   * @default PrimitiveType.TRIANGLES
    */
   this.primitiveType = defaultValue(
     options.primitiveType,
@@ -146,7 +144,7 @@ function Geometry(options) {
    * An optional bounding sphere that fully encloses the geometry.  This is
    * commonly used for culling.
    *
-   * @type BoundingSphere
+   * @type {BoundingSphere|undefined}
    *
    * @default undefined
    */

diff --git a/packages/engine/Source/Core/GeometryAttribute.js b/packages/engine/Source/Core/GeometryAttribute.js
@@ -11,10 +11,10 @@ import DeveloperError from "./DeveloperError.js";
  * @constructor
  *
  * @param {object} [options] Object with the following properties:
- * @param {ComponentDatatype} [options.componentDatatype] The datatype of each component in the attribute, e.g., individual elements in values.
- * @param {number} [options.componentsPerAttribute] A number between 1 and 4 that defines the number of components in an attributes.
+ * @param {ComponentDatatype} options.componentDatatype The datatype of each component in the attribute, e.g., individual elements in values.
+ * @param {number} options.componentsPerAttribute A number between 1 and 4 that defines the number of components in an attributes.
  * @param {boolean} [options.normalize=false] When <code>true</code> and <code>componentDatatype</code> is an integer format, indicate that the components should be mapped to the range [0, 1] (unsigned) or [-1, 1] (signed) when they are accessed as floating-point for rendering.
- * @param {number[]|Int8Array|Uint8Array|Int16Array|Uint16Array|Int32Array|Uint32Array|Float32Array|Float64Array} [options.values] The values for the attributes stored in a typed array.
+ * @param {number[]|Int8Array|Uint8Array|Int16Array|Uint16Array|Int32Array|Uint32Array|Float32Array|Float64Array} options.values The values for the attributes stored in a typed array.
  *
  * @exception {DeveloperError} options.componentsPerAttribute must be between 1 and 4.
  *
@@ -66,7 +66,6 @@ function GeometryAttribute(options) {
    *
    * @type {ComponentDatatype}
    *
-   * @default undefined
    */
   this.componentDatatype = options.componentDatatype;
 
@@ -77,8 +76,6 @@ function GeometryAttribute(options) {
    *
    * @type {number}
    *
-   * @default undefined
-   *
    * @example
    * attribute.componentDatatype = Cesium.ComponentDatatype.FLOAT;
    * attribute.componentsPerAttribute = 3;
@@ -122,8 +119,6 @@ function GeometryAttribute(options) {
    *
    * @type {number[]|Int8Array|Uint8Array|Int16Array|Uint16Array|Int32Array|Uint32Array|Float32Array|Float64Array}
    *
-   * @default undefined
-   *
    * @example
    * attribute.componentDatatype = Cesium.ComponentDatatype.FLOAT;
    * attribute.componentsPerAttribute = 3;

diff --git a/packages/engine/Source/Core/GeometryAttributes.js b/packages/engine/Source/Core/GeometryAttributes.js
@@ -19,7 +19,7 @@ function GeometryAttributes(options) {
    * 64-bit floating-point (for precision).  3 components per attribute.
    * </p>
    *
-   * @type GeometryAttribute
+   * @type {GeometryAttribute|undefined}
    *
    * @default undefined
    */
@@ -31,7 +31,7 @@ function GeometryAttributes(options) {
    * 32-bit floating-point.  3 components per attribute.
    * </p>
    *
-   * @type GeometryAttribute
+   * @type {GeometryAttribute|undefined}
    *
    * @default undefined
    */
@@ -43,7 +43,7 @@ function GeometryAttributes(options) {
    * 32-bit floating-point.  2 components per attribute
    * </p>
    *
-   * @type GeometryAttribute
+   * @type {GeometryAttribute|undefined}
    *
    * @default undefined
    */
@@ -55,7 +55,7 @@ function GeometryAttributes(options) {
    * 32-bit floating-point.  3 components per attribute.
    * </p>
    *
-   * @type GeometryAttribute
+   * @type {GeometryAttribute|undefined}
    *
    * @default undefined
    */
@@ -67,7 +67,7 @@ function GeometryAttributes(options) {
    * 32-bit floating-point.  3 components per attribute.
    * </p>
    *
-   * @type GeometryAttribute
+   * @type {GeometryAttribute|undefined}
    *
    * @default undefined
    */
@@ -79,7 +79,7 @@ function GeometryAttributes(options) {
    * 8-bit unsigned integer. 4 components per attribute.
    * </p>
    *
-   * @type GeometryAttribute
+   * @type {GeometryAttribute|undefined}
    *
    * @default undefined
    */

diff --git a/packages/engine/Source/Core/GeometryInstance.js b/packages/engine/Source/Core/GeometryInstance.js
@@ -62,7 +62,6 @@ function GeometryInstance(options) {
    *
    * @type Geometry
    *
-   * @default undefined
    */
   this.geometry = options.geometry;
 
@@ -83,7 +82,7 @@ function GeometryInstance(options) {
   /**
    * User-defined object returned when the instance is picked or used to get/set per-instance attributes.
    *
-   * @type {object}
+   * @type {object|undefined}
    *
    * @default undefined
    *
@@ -105,7 +104,7 @@ function GeometryInstance(options) {
    *
    * @type {object}
    *
-   * @default undefined
+   * @default {}
    */
   this.attributes = defaultValue(options.attributes, {});
 

diff --git a/packages/engine/Source/Core/GeometryInstanceAttribute.js b/packages/engine/Source/Core/GeometryInstanceAttribute.js
@@ -68,7 +68,6 @@ function GeometryInstanceAttribute(options) {
    *
    * @type ComponentDatatype
    *
-   * @default undefined
    */
   this.componentDatatype = options.componentDatatype;
 
@@ -79,8 +78,6 @@ function GeometryInstanceAttribute(options) {
    *
    * @type {number}
    *
-   * @default undefined
-   *
    * @example
    * show : new Cesium.GeometryInstanceAttribute({
    *   componentDatatype : Cesium.ComponentDatatype.UNSIGNED_BYTE,
@@ -123,8 +120,6 @@ function GeometryInstanceAttribute(options) {
    *
    * @type {number[]}
    *
-   * @default undefined
-   *
    * @example
    * show : new Cesium.GeometryInstanceAttribute({
    *   componentDatatype : Cesium.ComponentDatatype.UNSIGNED_BYTE,

diff --git a/packages/engine/Source/Core/GoogleEarthEnterpriseMetadata.js b/packages/engine/Source/Core/GoogleEarthEnterpriseMetadata.js
@@ -54,7 +54,7 @@ function GoogleEarthEnterpriseMetadata(resourceOrUrl) {
 
   /**
    * True if imagery is sent as a protocol buffer, false if sent as plain images. If undefined we will try both.
-   * @type {boolean}
+   * @type {boolean|undefined}
    * @default undefined
    */
   this.protoImagery = undefined;

diff --git a/packages/engine/Source/Core/OrthographicFrustum.js b/packages/engine/Source/Core/OrthographicFrustum.js
@@ -34,15 +34,15 @@ function OrthographicFrustum(options) {
 
   /**
    * The horizontal width of the frustum in meters.
-   * @type {number}
+   * @type {number|undefined}
    * @default undefined
    */
   this.width = options.width;
   this._width = undefined;
 
   /**
    * The aspect ratio of the frustum's width to it's height.
-   * @type {number}
+   * @type {number|undefined}
    * @default undefined
    */
   this.aspectRatio = options.aspectRatio;

diff --git a/packages/engine/Source/Core/OrthographicOffCenterFrustum.js b/packages/engine/Source/Core/OrthographicOffCenterFrustum.js
@@ -40,31 +40,31 @@ function OrthographicOffCenterFrustum(options) {
 
   /**
    * The left clipping plane.
-   * @type {number}
+   * @type {number|undefined}
    * @default undefined
    */
   this.left = options.left;
   this._left = undefined;
 
   /**
    * The right clipping plane.
-   * @type {number}
+   * @type {number|undefined}
    * @default undefined
    */
   this.right = options.right;
   this._right = undefined;
 
   /**
    * The top clipping plane.
-   * @type {number}
+   * @type {number|undefined}
    * @default undefined
    */
   this.top = options.top;
   this._top = undefined;
 
   /**
    * The bottom clipping plane.
-   * @type {number}
+   * @type {number|undefined}
    * @default undefined
    */
   this.bottom = options.bottom;

diff --git a/packages/engine/Source/Core/PerspectiveFrustum.js b/packages/engine/Source/Core/PerspectiveFrustum.js
@@ -41,7 +41,7 @@ function PerspectiveFrustum(options) {
    * The angle of the field of view (FOV), in radians.  This angle will be used
    * as the horizontal FOV if the width is greater than the height, otherwise
    * it will be the vertical FOV.
-   * @type {number}
+   * @type {number|undefined}
    * @default undefined
    */
   this.fov = options.fov;
@@ -52,7 +52,7 @@ function PerspectiveFrustum(options) {
 
   /**
    * The aspect ratio of the frustum's width to it's height.
-   * @type {number}
+   * @type {number|undefined}
    * @default undefined
    */
   this.aspectRatio = options.aspectRatio;
@@ -253,7 +253,7 @@ Object.defineProperties(PerspectiveFrustum.prototype, {
   /**
    * Gets the angle of the vertical field of view, in radians.
    * @memberof PerspectiveFrustum.prototype
-   * @type {number}
+   * @type {number|undefined}
    * @readonly
    * @default undefined
    */

diff --git a/packages/engine/Source/Core/PerspectiveOffCenterFrustum.js b/packages/engine/Source/Core/PerspectiveOffCenterFrustum.js
@@ -41,31 +41,31 @@ function PerspectiveOffCenterFrustum(options) {
 
   /**
    * Defines the left clipping plane.
-   * @type {number}
+   * @type {number|undefined}
    * @default undefined
    */
   this.left = options.left;
   this._left = undefined;
 
   /**
    * Defines the right clipping plane.
-   * @type {number}
+   * @type {number|undefined}
    * @default undefined
    */
   this.right = options.right;
   this._right = undefined;
 
   /**
    * Defines the top clipping plane.
-   * @type {number}
+   * @type {number|undefined}
    * @default undefined
    */
   this.top = options.top;
   this._top = undefined;
 
   /**
    * Defines the bottom clipping plane.
-   * @type {number}
+   * @type {number|undefined}
    * @default undefined
    */
   this.bottom = options.bottom;