Add eslint-jsdoc-plugin, autofix

Apps/Sandcastle/gallery/Custom DataSource.html

@@ -39,11 +39,9 @@
          * This class is an example of a custom DataSource.  It loads JSON data as
          * defined by Google's WebGL Globe, https://github.com/dataarts/webgl-globe.
          * @alias WebGLGlobeDataSource
-         * @constructor
-         *
+         * @class
          * @param {string} [name] The name of this data source.  If undefined, a name
          *                        will be derived from the url.
-         *
          * @example
          * const dataSource = new Cesium.WebGLGlobeDataSource();
          * dataSource.loadUrl('sample.json');
@@ -70,7 +68,7 @@
           /**
            * Gets a human-readable name for this instance.
            * @memberof WebGLGlobeDataSource.prototype
-           * @type {String}
+           * @type {string}
            */
           name: {
             get: function () {
@@ -99,7 +97,7 @@
           /**
            * Gets a value indicating if the data source is currently loading data.
            * @memberof WebGLGlobeDataSource.prototype
-           * @type {Boolean}
+           * @type {boolean}
            */
           isLoading: {
             get: function () {
@@ -156,7 +154,7 @@
            * so that only one series is viewed at a time.  Valid values are defined
            * in the seriesNames property.
            * @memberof WebGLGlobeDataSource.prototype
-           * @type {String}
+           * @type {string}
            */
           seriesToDisplay: {
             get: function () {
@@ -180,7 +178,7 @@
           /**
            * Gets or sets the scale factor applied to the height of each line.
            * @memberof WebGLGlobeDataSource.prototype
-           * @type {Number}
+           * @type {number}
            */
           heightScale: {
             get: function () {
@@ -196,7 +194,7 @@
           /**
            * Gets whether or not this data source should be displayed.
            * @memberof WebGLGlobeDataSource.prototype
-           * @type {Boolean}
+           * @type {boolean}
            */
           show: {
             get: function () {

Apps/Sandcastle/gallery/Custom Geocoder.html

@@ -48,13 +48,12 @@
         /**
          * This class is an example of a custom geocoder. It provides geocoding through the OpenStreetMap Nominatim service.
          * @alias OpenStreetMapNominatimGeocoder
-         * @constructor
+         * @class
          */
         function OpenStreetMapNominatimGeocoder() {}
 
         /**
          * 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[]>}
          */

Apps/Sandcastle/gallery/development/Custom Primitive.html

@@ -47,6 +47,7 @@
          * Simple example of writing a Primitive from scratch. This
          * primitive displays a procedurally-generated surface at a given
          * position on the globe.
+         * @param cartographicPosition
          */
         function CustomPrimitive(cartographicPosition) {
           this.show = true;
@@ -84,6 +85,8 @@
         /**
          * generate a quad that's subdivided into faceResolution x faceResolution quads.
          * The vertices will be adjusted in the vertex shader.
+         * @param faceResolution
+         * @param halfWidthMeters
          */
         function generateVertices(faceResolution, halfWidthMeters) {
           const vertexResolution = faceResolution + 1;
@@ -109,6 +112,7 @@
 
         /**
          * Tessellate a big square region into faceResolution x faceResolution quads
+         * @param faceResolution
          */
         function generateIndices(faceResolution) {
           const indicesPerQuad = 6;
@@ -141,6 +145,7 @@
         const scratchColor = new Cesium.Color();
         /**
          * Generate a 1D texture for the color palette
+         * @param context
          */
         function generateTexture(context) {
           const width = 256;

Specs/ImplicitTilingTester.js

@@ -45,15 +45,13 @@ function ImplicitTilingTester() {}
  * @property {Uint8Array} [subtreeJson] The JSON portion of the subtree file. Mutually exclusive with subtreeBuffer.
  * @property {Uint8Array} [subtreeBuffer] A typed array storing the contents of the subtree file (including the internal buffer). Mutually exclusive with subtreeJson.
  * @property {Uint8Array} externalBuffer A typed array representing an external .bin file. This is always returned, but it may be an empty typed array.
-
  */
 
 /**
  * Generate a subtree buffer
  * @param {SubtreeDescription} subtreeDescription A JSON description of the subtree's structure and values
  * @param {boolean} constantOnly true if all the bitstreams are constant, i.e. no buffers/bufferViews are needed.
- * @return {GeneratedSubtree} The procedurally generated subtree and an external buffer.
- *
+ * @returns {GeneratedSubtree} The procedurally generated subtree and an external buffer.
  * @example
  *  const subtreeDescription = {
  *    tileAvailability: {
@@ -80,7 +78,6 @@ function ImplicitTilingTester() {}
  *  const results = ImplicitTilingTester.generateSubtreeBuffers(
  *    subtreeDescription
  *  );
- *
  * @private
  */
 ImplicitTilingTester.generateSubtreeBuffers = function (

Specs/getArguments.js

@@ -11,7 +11,7 @@
  * constructor, so it never compares Jasmine-equal to an array.  This function lets
  * us create an arguments array.
  * @alias getArguments
- * @return {Array} The arguments passed to the function.
+ * @returns {Array} The arguments passed to the function.
  */
 function getArguments() {
   return arguments;

eslint.config.js

@@ -1,6 +1,7 @@
 import globals from "globals";
 import html from "eslint-plugin-html";
 import configCesium from "eslint-config-cesium";
+import jsdoc from "eslint-plugin-jsdoc";
 
 export default [
   {
@@ -42,13 +43,33 @@ export default [
   {
     files: ["packages/**/*.js", "Apps/**/*.js", "Specs/**/*.js", "**/*.html"],
     ...configCesium.configs.browser,
-    plugins: { html },
+    plugins: { html, jsdoc },
     rules: {
       ...configCesium.configs.browser.rules,
+      ...jsdoc.configs["flat/recommended-error"].rules,
       "no-unused-vars": [
         "error",
         { vars: "all", args: "none", caughtErrors: "none" },
       ],
+      "jsdoc/require-jsdoc": "off", // Only lint existing jsdoc
+      "jsdoc/no-undefined-types": "off", // Ignore types for now
+      "jsdoc/require-returns": "off",
+      "jsdoc/require-returns-description": "off",
+      "jsdoc/require-returns-type": "off",
+      "jsdoc/require-returns-check": "off",
+      "jsdoc/require-param-type": "off",
+      "jsdoc/require-param-description": "off",
+      "jsdoc/require-property-description": "off",
+      "jsdoc/require-description": "off",
+      "jsdoc/check-param-names": "off",
+      "jsdoc/check-property-names": "off",
+      "jsdoc/check-types": "off",
+      "jsdoc/valid-types": "off",
+      "jsdoc/tag-lines": "off",
+      "jsdoc/check-tag-names": "off",
+      "jsdoc/no-defaults": "off",
+      "jsdoc/no-multi-asterisks": "off",
+      "jsdoc/check-access": "off",
     },
   },
   {

package.json

@@ -62,6 +62,7 @@
     "eslint": "^9.1.1",
     "eslint-config-cesium": "^11.0.1",
     "eslint-plugin-html": "^8.1.1",
+    "eslint-plugin-jsdoc": "^48.2.7",
     "express": "^4.17.1",
     "globals": "^15.1.0",
     "globby": "^14.0.0",

packages/engine/Source/Core/ApproximateTerrainHeights.js

@@ -36,7 +36,7 @@ const ApproximateTerrainHeights = {};
 
 /**
  * Initializes the minimum and maximum terrain heights
- * @return {Promise<void>}
+ * @returns {Promise<void>}
  */
 ApproximateTerrainHeights.initialize = function () {
   let initPromise = ApproximateTerrainHeights._initPromise;
@@ -56,8 +56,8 @@ ApproximateTerrainHeights.initialize = function () {
 /**
  * Computes the minimum and maximum terrain heights for a given rectangle
  * @param {Rectangle} rectangle The bounding rectangle
- * @param {Ellipsoid} [ellipsoid=Ellipsoid.WGS84] The ellipsoid
- * @return {{minimumTerrainHeight: number, maximumTerrainHeight: number}}
+ * @param {Ellipsoid} [ellipsoid] The ellipsoid
+ * @returns {{minimumTerrainHeight: number, maximumTerrainHeight: number}}
  */
 ApproximateTerrainHeights.getMinimumMaximumHeights = function (
   rectangle,
@@ -130,8 +130,8 @@ ApproximateTerrainHeights.getMinimumMaximumHeights = function (
 /**
  * Computes the bounding sphere based on the tile heights in the rectangle
  * @param {Rectangle} rectangle The bounding rectangle
- * @param {Ellipsoid} [ellipsoid=Ellipsoid.WGS84] The ellipsoid
- * @return {BoundingSphere} The result bounding sphere
+ * @param {Ellipsoid} [ellipsoid] The ellipsoid
+ * @returns {BoundingSphere} The result bounding sphere
  */
 ApproximateTerrainHeights.getBoundingSphere = function (rectangle, ellipsoid) {
   //>>includeStart('debug', pragmas.debug);

packages/engine/Source/Core/ArcGISTiledElevationTerrainProvider.js

@@ -22,10 +22,9 @@ import WebMercatorTilingScheme from "./WebMercatorTilingScheme.js";
 const ALL_CHILDREN = 15;
 
 /**
- * @typedef {Object} ArcGISTiledElevationTerrainProvider.ConstructorOptions
+ * @typedef {object} ArcGISTiledElevationTerrainProvider.ConstructorOptions
  *
  * Initialization options for the ArcGISTiledElevationTerrainProvider constructor
- *
  * @property {string} [token] The authorization token to use to connect to the service.
  * @property {Ellipsoid} [ellipsoid] The ellipsoid.  If the tilingScheme is specified,
  *                    this parameter is ignored and the tiling scheme's ellipsoid is used instead.
@@ -34,10 +33,8 @@ const ALL_CHILDREN = 15;
 
 /**
  * Used to track creation details while fetching initial metadata
- *
- * @constructor
+ * @class
  * @private
- *
  * @param {ArcGISTiledElevationTerrainProvider.ConstructorOptions} [options] An object describing initialization options.
  */
 function TerrainProviderBuilder(options) {
@@ -58,9 +55,7 @@ function TerrainProviderBuilder(options) {
 
 /**
  * Complete ArcGISTiledElevationTerrainProvider creation based on builder values.
- *
  * @private
- *
  * @param {ArcGISTiledElevationTerrainProvider} provider
  */
 TerrainProviderBuilder.prototype.build = function (provider) {
@@ -217,18 +212,14 @@ async function requestMetadata(
  *
  * A {@link TerrainProvider} that produces terrain geometry by tessellating height maps
  * retrieved from Elevation Tiles of an an ArcGIS ImageService.
- *
  * @alias ArcGISTiledElevationTerrainProvider
- * @constructor
- *
+ * @class
  * @param {CesiumTerrainProvider.ConstructorOptions} [options] A url or an object describing initialization options
- *
  * @example
  * const terrainProvider = await Cesium.ArcGISTiledElevationTerrainProvider.fromUrl("https://elevation3d.arcgis.com/arcgis/rest/services/WorldElevation3D/Terrain3D/ImageServer", {
  *   token: "KED1aF_I4UzXOHy3BnhwyBHU4l5oY6rO6walkmHoYqGp4XyIWUd5YZUC1ZrLAzvV40pR6gBXQayh0eFA8m6vPg.."
  * });
  * viewer.terrainProvider = terrainProvider;
- *
  * @see TerrainProvider
  */
 function ArcGISTiledElevationTerrainProvider(options) {
@@ -336,19 +327,16 @@ Object.defineProperties(ArcGISTiledElevationTerrainProvider.prototype, {
 /**
  * Creates a {@link TerrainProvider} that produces terrain geometry by tessellating height maps
  * retrieved from Elevation Tiles of an an ArcGIS ImageService.
- *
- * @param {Resource|String|Promise<Resource>|Promise<String>} url The URL of the ArcGIS ImageServer service.
+ * @param {Resource | string | Promise<Resource> | Promise<string>} url The URL of the ArcGIS ImageServer service.
  * @param {ArcGISTiledElevationTerrainProvider.ConstructorOptions} [options] A url or an object describing initialization options.
  * @returns {Promise<ArcGISTiledElevationTerrainProvider>}
- *
  * @example
  * const terrainProvider = await Cesium.ArcGISTiledElevationTerrainProvider.fromUrl("https://elevation3d.arcgis.com/arcgis/rest/services/WorldElevation3D/Terrain3D/ImageServer", {
  *   token: "KED1aF_I4UzXOHy3BnhwyBHU4l5oY6rO6walkmHoYqGp4XyIWUd5YZUC1ZrLAzvV40pR6gBXQayh0eFA8m6vPg.."
  * });
  * viewer.terrainProvider = terrainProvider;
- *
- * @exception {RuntimeError} metadata specifies invalid spatial reference
- * @exception {RuntimeError} metadata does not specify tileInfo
+ * @throws {RuntimeError} metadata specifies invalid spatial reference
+ * @throws {RuntimeError} metadata does not specify tileInfo
  */
 ArcGISTiledElevationTerrainProvider.fromUrl = async function (url, options) {
   //>>includeStart('debug', pragmas.debug);
@@ -387,7 +375,6 @@ ArcGISTiledElevationTerrainProvider.fromUrl = async function (url, options) {
 /**
  * Requests the geometry for a given tile. The result includes terrain
  * data and indicates that all child tiles are available.
- *
  * @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.
@@ -491,7 +478,6 @@ function isTileAvailable(that, level, x, y) {
 
 /**
  * Gets the maximum geometric error allowed in a tile at a given level.
- *
  * @param {number} level The tile level for which to get the maximum geometric error.
  * @returns {number} The maximum geometric error.
  */
@@ -503,7 +489,6 @@ ArcGISTiledElevationTerrainProvider.prototype.getLevelMaximumGeometricError = fu
 
 /**
  * Determines whether data for a tile is available to be loaded.
- *
  * @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.
@@ -530,7 +515,6 @@ ArcGISTiledElevationTerrainProvider.prototype.getTileDataAvailable = function (
 
 /**
  * Makes sure we load availability data for a tile
- *
  * @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.

packages/engine/Source/Core/ArcType.js

@@ -1,28 +1,24 @@
 /**
  * ArcType defines the path that should be taken connecting vertices.
- *
  * @enum {number}
  */
 const ArcType = {
   /**
    * Straight line that does not conform to the surface of the ellipsoid.
-   *
    * @type {number}
    * @constant
    */
   NONE: 0,
 
   /**
    * Follow geodesic path.
-   *
    * @type {number}
    * @constant
    */
   GEODESIC: 1,
 
   /**
    * Follow rhumb or loxodrome path.
-   *
    * @type {number}
    * @constant
    */

packages/engine/Source/Core/ArticulationStageType.js

@@ -1,10 +1,8 @@
 /**
  * An enum describing the type of motion that is defined by an articulation stage
  * in the AGI_articulations extension.
- *
  * @alias {ArticulationStageType}
  * @enum {string}
- *
  * @private
  */
 const ArticulationStageType = {