Merge pull request #8904 from CesiumGS/issue8898

Improve JSDoc/TypeScript support for Material properties

CHANGES.md

@@ -8,6 +8,8 @@
 
 ##### Fixes :wrench:
 
+- Improved `MaterialProperty` JSDoc and TypeScript type definitions, which were missing the ability to take primitive types in addition to Property instances in their constructor.
+- Fixed `EllipsoidGeodesic` JSDoc and TypeScript type definitions which incorrectly listed `result` as required.
 - Fixed a bug with handling of PixelFormat's flipY. [#8893](https://github.com/CesiumGS/cesium/pull/8893)
 - Fixed a memory leak where some 3D Tiles requests were being unintentionally retained after the requests were cancelled. [#8843](https://github.com/CesiumGS/cesium/pull/8843)
 

Source/Core/EllipsoidGeodesic.js

@@ -401,7 +401,7 @@ EllipsoidGeodesic.prototype.setEndPoints = function (start, end) {
  * Provides the location of a point at the indicated portion along the geodesic.
  *
  * @param {Number} fraction The portion of the distance between the initial and final points.
- * @param {Cartographic} result The object in which to store the result.
+ * @param {Cartographic} [result] The object in which to store the result.
  * @returns {Cartographic} The location of the point along the geodesic.
  */
 EllipsoidGeodesic.prototype.interpolateUsingFraction = function (
@@ -418,7 +418,7 @@ EllipsoidGeodesic.prototype.interpolateUsingFraction = function (
  * Provides the location of a point at the indicated distance along the geodesic.
  *
  * @param {Number} distance The distance from the inital point to the point of interest along the geodesic
- * @param {Cartographic} result The object in which to store the result.
+ * @param {Cartographic} [result] The object in which to store the result.
  * @returns {Cartographic} The location of the point along the geodesic.
  *
  * @exception {DeveloperError} start and end must be set before calling function interpolateUsingSurfaceDistance

Source/DataSources/BoxGraphics.js

@@ -83,7 +83,7 @@ Object.defineProperties(BoxGraphics.prototype, {
   /**
    * Gets or sets {@link Cartesian3} Property property specifying the length, width, and height of the box.
    * @memberof BoxGraphics.prototype
-   * @type {Property}
+   * @type {Property|undefined}
    */
   dimensions: createPropertyDescriptor("dimensions"),
 

Source/DataSources/CheckerboardMaterialProperty.js

@@ -16,9 +16,9 @@ var defaultRepeat = new Cartesian2(2.0, 2.0);
  * @constructor
  *
  * @param {Object} [options] Object with the following properties:
- * @param {Property} [options.evenColor=Color.WHITE] A Property specifying the first {@link Color}.
- * @param {Property} [options.oddColor=Color.BLACK] A Property specifying the second {@link Color}.
- * @param {Property} [options.repeat=new Cartesian2(2.0, 2.0)] A {@link Cartesian2} Property specifying how many times the tiles repeat in each direction.
+ * @param {Property|Color} [options.evenColor=Color.WHITE] A Property specifying the first {@link Color}.
+ * @param {Property|Color} [options.oddColor=Color.BLACK] A Property specifying the second {@link Color}.
+ * @param {Property|Cartesian2} [options.repeat=new Cartesian2(2.0, 2.0)] A {@link Cartesian2} Property specifying how many times the tiles repeat in each direction.
  */
 function CheckerboardMaterialProperty(options) {
   options = defaultValue(options, defaultValue.EMPTY_OBJECT);
@@ -73,23 +73,23 @@ Object.defineProperties(CheckerboardMaterialProperty.prototype, {
   /**
    * Gets or sets the Property specifying the first {@link Color}.
    * @memberof CheckerboardMaterialProperty.prototype
-   * @type {Property}
+   * @type {Property|undefined}
    * @default Color.WHITE
    */
   evenColor: createPropertyDescriptor("evenColor"),
 
   /**
    * Gets or sets the Property specifying the second {@link Color}.
    * @memberof CheckerboardMaterialProperty.prototype
-   * @type {Property}
+   * @type {Property|undefined}
    * @default Color.BLACK
    */
   oddColor: createPropertyDescriptor("oddColor"),
 
   /**
    * Gets or sets the {@link Cartesian2} Property specifying how many times the tiles repeat in each direction.
    * @memberof CheckerboardMaterialProperty.prototype
-   * @type {Property}
+   * @type {Property|undefined}
    * @default new Cartesian2(2.0, 2.0)
    */
   repeat: createPropertyDescriptor("repeat"),

Source/DataSources/ColorMaterialProperty.js

@@ -7,7 +7,7 @@ import Property from "./Property.js";
 /**
  * A {@link MaterialProperty} that maps to solid color {@link Material} uniforms.
  *
- * @param {Property} [color=Color.WHITE] The {@link Color} Property to be used.
+ * @param {Property|Color} [color=Color.WHITE] The {@link Color} Property to be used.
  *
  * @alias ColorMaterialProperty
  * @constructor
@@ -53,7 +53,7 @@ Object.defineProperties(ColorMaterialProperty.prototype, {
   /**
    * Gets or sets the {@link Color} {@link Property}.
    * @memberof ColorMaterialProperty.prototype
-   * @type {Property}
+   * @type {Property|undefined}
    * @default Color.WHITE
    */
   color: createPropertyDescriptor("color"),

Source/DataSources/GridMaterialProperty.js

@@ -17,11 +17,11 @@ var defaultLineThickness = new Cartesian2(1, 1);
  * @alias GridMaterialProperty
  *
  * @param {Object} [options] Object with the following properties:
- * @param {Property} [options.color=Color.WHITE] A Property specifying the grid {@link Color}.
- * @param {Property} [options.cellAlpha=0.1] A numeric Property specifying cell alpha values.
- * @param {Property} [options.lineCount=new Cartesian2(8, 8)] A {@link Cartesian2} Property specifying the number of grid lines along each axis.
- * @param {Property} [options.lineThickness=new Cartesian2(1.0, 1.0)] A {@link Cartesian2} Property specifying the thickness of grid lines along each axis.
- * @param {Property} [options.lineOffset=new Cartesian2(0.0, 0.0)] A {@link Cartesian2} Property specifying starting offset of grid lines along each axis.
+ * @param {Property|Color} [options.color=Color.WHITE] A Property specifying the grid {@link Color}.
+ * @param {Property|Number} [options.cellAlpha=0.1] A numeric Property specifying cell alpha values.
+ * @param {Property|Cartesian2} [options.lineCount=new Cartesian2(8, 8)] A {@link Cartesian2} Property specifying the number of grid lines along each axis.
+ * @param {Property|Cartesian2} [options.lineThickness=new Cartesian2(1.0, 1.0)] A {@link Cartesian2} Property specifying the thickness of grid lines along each axis.
+ * @param {Property|Cartesian2} [options.lineOffset=new Cartesian2(0.0, 0.0)] A {@link Cartesian2} Property specifying starting offset of grid lines along each axis.
  *
  * @constructor
  */
@@ -86,39 +86,39 @@ Object.defineProperties(GridMaterialProperty.prototype, {
   /**
    * Gets or sets the Property specifying the grid {@link Color}.
    * @memberof GridMaterialProperty.prototype
-   * @type {Property}
+   * @type {Property|undefined}
    * @default Color.WHITE
    */
   color: createPropertyDescriptor("color"),
 
   /**
    * Gets or sets the numeric Property specifying cell alpha values.
    * @memberof GridMaterialProperty.prototype
-   * @type {Property}
+   * @type {Property|undefined}
    * @default 0.1
    */
   cellAlpha: createPropertyDescriptor("cellAlpha"),
 
   /**
    * Gets or sets the {@link Cartesian2} Property specifying the number of grid lines along each axis.
    * @memberof GridMaterialProperty.prototype
-   * @type {Property}
+   * @type {Property|undefined}
    * @default new Cartesian2(8.0, 8.0)
    */
   lineCount: createPropertyDescriptor("lineCount"),
 
   /**
    * Gets or sets the {@link Cartesian2} Property specifying the thickness of grid lines along each axis.
    * @memberof GridMaterialProperty.prototype
-   * @type {Property}
+   * @type {Property|undefined}
    * @default new Cartesian2(1.0, 1.0)
    */
   lineThickness: createPropertyDescriptor("lineThickness"),
 
   /**
    * Gets or sets the {@link Cartesian2} Property specifying the starting offset of grid lines along each axis.
    * @memberof GridMaterialProperty.prototype
-   * @type {Property}
+   * @type {Property|undefined}
    * @default new Cartesian2(0.0, 0.0)
    */
   lineOffset: createPropertyDescriptor("lineOffset"),

Source/DataSources/ImageMaterialProperty.js

@@ -16,10 +16,10 @@ var defaultColor = Color.WHITE;
  * @constructor
  *
  * @param {Object} [options] Object with the following properties:
- * @param {Property} [options.image] A Property specifying the Image, URL, Canvas, or Video.
- * @param {Property} [options.repeat=new Cartesian2(1.0, 1.0)] A {@link Cartesian2} Property specifying the number of times the image repeats in each direction.
- * @param {Property} [options.color=Color.WHITE] The color applied to the image
- * @param {Property} [options.transparent=false] Set to true when the image has transparency (for example, when a png has transparent sections)
+ * @param {Property|String|HTMLImageElement|HTMLCanvasElement|HTMLVideoElement} [options.image] A Property specifying the Image, URL, Canvas, or Video.
+ * @param {Property|Cartesian2} [options.repeat=new Cartesian2(1.0, 1.0)] A {@link Cartesian2} Property specifying the number of times the image repeats in each direction.
+ * @param {Property|Color} [options.color=Color.WHITE] The color applied to the image
+ * @param {Property|Boolean} [options.transparent=false] Set to true when the image has transparency (for example, when a png has transparent sections)
  */
 function ImageMaterialProperty(options) {
   options = defaultValue(options, defaultValue.EMPTY_OBJECT);
@@ -75,30 +75,30 @@ Object.defineProperties(ImageMaterialProperty.prototype, {
   /**
    * Gets or sets the Property specifying Image, URL, Canvas, or Video to use.
    * @memberof ImageMaterialProperty.prototype
-   * @type {Property}
+   * @type {Property|undefined}
    */
   image: createPropertyDescriptor("image"),
 
   /**
    * Gets or sets the {@link Cartesian2} Property specifying the number of times the image repeats in each direction.
    * @memberof ImageMaterialProperty.prototype
-   * @type {Property}
+   * @type {Property|undefined}
    * @default new Cartesian2(1, 1)
    */
   repeat: createPropertyDescriptor("repeat"),
 
   /**
    * Gets or sets the Color Property specifying the desired color applied to the image.
    * @memberof ImageMaterialProperty.prototype
-   * @type {Property}
+   * @type {Property|undefined}
    * @default 1.0
    */
   color: createPropertyDescriptor("color"),
 
   /**
    * Gets or sets the Boolean Property specifying whether the image has transparency
    * @memberof ImageMaterialProperty.prototype
-   * @type {Property}
+   * @type {Property|undefined}
    * @default 1.0
    */
   transparent: createPropertyDescriptor("transparent"),

Source/DataSources/NodeTransformationProperty.js

@@ -70,23 +70,23 @@ Object.defineProperties(NodeTransformationProperty.prototype, {
   /**
    * Gets or sets the {@link Cartesian3} Property specifying the (x, y, z) translation to apply to the node.
    * @memberof NodeTransformationProperty.prototype
-   * @type {Property}
+   * @type {Property|undefined}
    * @default Cartesian3.ZERO
    */
   translation: createPropertyDescriptor("translation"),
 
   /**
    * Gets or sets the {@link Quaternion} Property specifying the (x, y, z, w) rotation to apply to the node.
    * @memberof NodeTransformationProperty.prototype
-   * @type {Property}
+   * @type {Property|undefined}
    * @default Quaternion.IDENTITY
    */
   rotation: createPropertyDescriptor("rotation"),
 
   /**
    * Gets or sets the {@link Cartesian3} Property specifying the (x, y, z) scaling to apply to the node.
    * @memberof NodeTransformationProperty.prototype
-   * @type {Property}
+   * @type {Property|undefined}
    * @default new Cartesian3(1.0, 1.0, 1.0)
    */
   scale: createPropertyDescriptor("scale"),

Source/DataSources/PolylineArrowMaterialProperty.js

@@ -7,7 +7,7 @@ import Property from "./Property.js";
 /**
  * A {@link MaterialProperty} that maps to PolylineArrow {@link Material} uniforms.
  *
- * @param {Property} [color=Color.WHITE] The {@link Color} Property to be used.
+ * @param {Property|Color} [color=Color.WHITE] The {@link Color} Property to be used.
  *
  * @alias PolylineArrowMaterialProperty
  * @constructor
@@ -51,7 +51,7 @@ Object.defineProperties(PolylineArrowMaterialProperty.prototype, {
   /**
    * Gets or sets the {@link Color} {@link Property}.
    * @memberof PolylineArrowMaterialProperty.prototype
-   * @type {Property}
+   * @type {Property|undefined}
    * @default Color.WHITE
    */
   color: createPropertyDescriptor("color"),

Source/DataSources/PolylineDashMaterialProperty.js

@@ -16,10 +16,10 @@ var defaultDashPattern = 255.0;
  * @constructor
  *
  * @param {Object} [options] Object with the following properties:
- * @param {Property} [options.color=Color.WHITE] A Property specifying the {@link Color} of the line.
- * @param {Property} [options.gapColor=Color.TRANSPARENT] A Property specifying the {@link Color} of the gaps in the line.
- * @param {Property} [options.dashLength=16.0] A numeric Property specifying the length of the dash pattern in pixels.
- * @param {Property} [options.dashPattern=255.0] A numeric Property specifying a 16 bit pattern for the dash
+ * @param {Property|Color} [options.color=Color.WHITE] A Property specifying the {@link Color} of the line.
+ * @param {Property|Color} [options.gapColor=Color.TRANSPARENT] A Property specifying the {@link Color} of the gaps in the line.
+ * @param {Property|Number} [options.dashLength=16.0] A numeric Property specifying the length of the dash pattern in pixels.
+ * @param {Property|Number} [options.dashPattern=255.0] A numeric Property specifying a 16 bit pattern for the dash
  */
 function PolylineDashMaterialProperty(options) {
   options = defaultValue(options, defaultValue.EMPTY_OBJECT);
@@ -74,28 +74,28 @@ Object.defineProperties(PolylineDashMaterialProperty.prototype, {
   /**
    * Gets or sets the Property specifying the {@link Color} of the line.
    * @memberof PolylineDashMaterialProperty.prototype
-   * @type {Property}
+   * @type {Property|undefined}
    */
   color: createPropertyDescriptor("color"),
 
   /**
    * Gets or sets the Property specifying the {@link Color} of the gaps in the line.
    * @memberof PolylineDashMaterialProperty.prototype
-   * @type {Property}
+   * @type {Property|undefined}
    */
   gapColor: createPropertyDescriptor("gapColor"),
 
   /**
    * Gets or sets the numeric Property specifying the length of a dash cycle
    * @memberof PolylineDashMaterialProperty.prototype
-   * @type {Property}
+   * @type {Property|undefined}
    */
   dashLength: createPropertyDescriptor("dashLength"),
 
   /**
    * Gets or sets the numeric Property specifying a dash pattern
    * @memberof PolylineDashMaterialProperty.prototype
-   * @type {Property}
+   * @type {Property|undefined}
    */
   dashPattern: createPropertyDescriptor("dashPattern"),
 });

Source/DataSources/PolylineGlowMaterialProperty.js

@@ -15,9 +15,9 @@ var defaultTaperPower = 1.0;
  * @constructor
  *
  * @param {Object} [options] Object with the following properties:
- * @param {Property} [options.color=Color.WHITE] A Property specifying the {@link Color} of the line.
- * @param {Property} [options.glowPower=0.25] A numeric Property specifying the strength of the glow, as a percentage of the total line width.
- * @param {Property} [options.taperPower=1.0] A numeric Property specifying the strength of the tapering effect, as a percentage of the total line length.  If 1.0 or higher, no taper effect is used.
+ * @param {Property|Color} [options.color=Color.WHITE] A Property specifying the {@link Color} of the line.
+ * @param {Property|Number} [options.glowPower=0.25] A numeric Property specifying the strength of the glow, as a percentage of the total line width.
+ * @param {Property|Number} [options.taperPower=1.0] A numeric Property specifying the strength of the tapering effect, as a percentage of the total line length.  If 1.0 or higher, no taper effect is used.
  */
 function PolylineGlowMaterialProperty(options) {
   options = defaultValue(options, defaultValue.EMPTY_OBJECT);
@@ -66,21 +66,21 @@ Object.defineProperties(PolylineGlowMaterialProperty.prototype, {
   /**
    * Gets or sets the Property specifying the {@link Color} of the line.
    * @memberof PolylineGlowMaterialProperty.prototype
-   * @type {Property}
+   * @type {Property|undefined}
    */
   color: createPropertyDescriptor("color"),
 
   /**
    * Gets or sets the numeric Property specifying the strength of the glow, as a percentage of the total line width (less than 1.0).
    * @memberof PolylineGlowMaterialProperty.prototype
-   * @type {Property}
+   * @type {Property|undefined}
    */
   glowPower: createPropertyDescriptor("glowPower"),
 
   /**
    * Gets or sets the numeric Property specifying the strength of the tapering effect, as a percentage of the total line length.  If 1.0 or higher, no taper effect is used.
    * @memberof PolylineGlowMaterialProperty.prototype
-   * @type {Property}
+   * @type {Property|undefined}
    */
   taperPower: createPropertyDescriptor("taperPower"),
 });

Source/DataSources/PolylineOutlineMaterialProperty.js

@@ -15,9 +15,9 @@ var defaultOutlineWidth = 1.0;
  * @constructor
  *
  * @param {Object} [options] Object with the following properties:
- * @param {Property} [options.color=Color.WHITE] A Property specifying the {@link Color} of the line.
- * @param {Property} [options.outlineColor=Color.BLACK] A Property specifying the {@link Color} of the outline.
- * @param {Property} [options.outlineWidth=1.0] A numeric Property specifying the width of the outline, in pixels.
+ * @param {Property|Color} [options.color=Color.WHITE] A Property specifying the {@link Color} of the line.
+ * @param {Property|Color} [options.outlineColor=Color.BLACK] A Property specifying the {@link Color} of the outline.
+ * @param {Property|Number} [options.outlineWidth=1.0] A numeric Property specifying the width of the outline, in pixels.
  */
 function PolylineOutlineMaterialProperty(options) {
   options = defaultValue(options, defaultValue.EMPTY_OBJECT);
@@ -70,23 +70,23 @@ Object.defineProperties(PolylineOutlineMaterialProperty.prototype, {
   /**
    * Gets or sets the Property specifying the {@link Color} of the line.
    * @memberof PolylineOutlineMaterialProperty.prototype
-   * @type {Property}
+   * @type {Property|undefined}
    * @default Color.WHITE
    */
   color: createPropertyDescriptor("color"),
 
   /**
    * Gets or sets the Property specifying the {@link Color} of the outline.
    * @memberof PolylineOutlineMaterialProperty.prototype
-   * @type {Property}
+   * @type {Property|undefined}
    * @default Color.BLACK
    */
   outlineColor: createPropertyDescriptor("outlineColor"),
 
   /**
    * Gets or sets the numeric Property specifying the width of the outline.
    * @memberof PolylineOutlineMaterialProperty.prototype
-   * @type {Property}
+   * @type {Property|undefined}
    * @default 1.0
    */
   outlineWidth: createPropertyDescriptor("outlineWidth"),

Source/DataSources/ReferenceProperty.js

@@ -191,7 +191,7 @@ Object.defineProperties(ReferenceProperty.prototype, {
   /**
    * Gets the resolved instance of the underlying referenced property.
    * @memberof ReferenceProperty.prototype
-   * @type {Property}
+   * @type {Property|undefined}
    * @readonly
    */
   resolvedProperty: {