Add JSDocs @SInCE tags to new methods

Issue #1720

src/js/collections/maps/AssetColors.js

@@ -38,6 +38,7 @@ define(
          * Add custom sort functionality such that values are sorted
          * numerically, but keep the special value key words "min" and "max" at
          * the beginning or end of the collection, respectively.
+         * @since x.x.x
          */
         comparator: function (color) {
           let value = color.get('value');
@@ -68,6 +69,7 @@ define(
          * array of the values for that attribute.
          * @param {string} attr - The attribute to get the values for.
          * @return {Array}
+         * @since x.x.x
          */
         getAttr: function(attr) {
           return this.map(function (model) {

src/js/collections/maps/Features.js

@@ -94,6 +94,7 @@ define(
          * @param {Feature|Cesium.Cesium3DTilesetFeature|Cesium.Entity} featureObject 
          * @returns {boolean} Returns true if the given feature object is in this
          * collection, false otherwise.
+         * @since x.x.x
          */
         containsFeature: function (featureObject) {
           if (!featureObject) return false;

src/js/collections/maps/MapAssets.js

@@ -198,6 +198,7 @@ define([
        * the MapAsset model.
        * @returns {MapAsset} - Returns the MapAsset model that was added to the
        * collection.
+       * @since x.x.x
        */
       addAsset: function (asset, mapModel) {
         try {
@@ -231,6 +232,7 @@ define([
        * feature selected from the map view widget.
        * @returns {Object[]} - Returns an array of attributes that can be used
        * to create new Feature models.
+       * @since x.x.x
        */
       getFeatureAttributes: function (features) {
         return features.map((feature) => {

src/js/models/connectors/Map-Search-Filters.js

@@ -139,7 +139,6 @@ define([
           : [filtersArray];
 
         filtersArray.forEach((filterGroup) => {
-          // filterGroupJSON.isUIFilterType = true; // TODO - do we need this?
           const filterGroupModel =
             filterGroup instanceof FilterGroup
               ? filterGroup

src/js/models/connectors/Map-Search.js

@@ -280,18 +280,6 @@ define([
         return geohashFacets.flatMap((key) => facetCounts[key]);
       },
 
-      /**
-       * Get the total number of results from the Search results.
-       * @returns {number} The total number of results or null if there are no
-       * Search results.
-       * TODO: This is not currently used, but it could be used to set a
-       * totalCount property on the Geohash layer, and scale the colors based
-       * on this max.
-       */
-      getTotalNumberOfResults: function () {
-        return this.get("searchResults")?.getNumFound();
-      },
-
       /**
        * Update the Geohash layer in the Map model with the new facet counts
        * from the Search results.

src/js/models/filters/SpatialFilter.js

@@ -68,6 +68,7 @@ define([
       /**
        * Returns true if the filter has a valid set of coordinates
        * @returns {boolean} True if the filter has coordinates
+       * @since x.x.x
        */
       hasCoordinates: function () {
         return (
@@ -84,7 +85,7 @@ define([
        * Coordinates will be adjusted if they are out of bounds.
        * @param {boolean} [silent=true] - Whether to trigger a change event in
        * the case where the coordinates are adjusted
-       *
+       * @since x.x.x
        */
       validateCoordinates: function (silent = true) {
         if (!this.hasCoordinates()) return;
@@ -105,6 +106,7 @@ define([
       /**
        * Set a listener that updates the filter when the coordinates & height
        * change
+       * @since x.x.x
        */
       setListeners: function () {
         const extentEvents =
@@ -130,6 +132,7 @@ define([
       /**
        * Returns true if the bounds set on the filter covers the entire earth
        * @returns {boolean}
+       * @since x.x.x
        */
       coversEarth: function () {
         const bounds = this.getBounds();
@@ -202,24 +205,27 @@ define([
 
       /**
        * Builds a query string that represents this spatial filter
+       * @param {boolean} [consolidate=false] Whether to consolidate the set of
+       * geohashes to the smallest set that covers the same area (i.e. merges
+       * geohashes together when there are complete groups of 32). This is false
+       * by default because geohashes are already consolidated when they are
+       * added as the spatial filter is used right now.
        * @return {string} The query fragment
        * @since x.x.x
        */
-      getQuery: function () {
+      getQuery: function (consolidate = false) {
         try {
           // Methods in the geohash collection allow us make efficient queries
           const hashes = this.get("values");
           let geohashes = new Geohashes(hashes.map((h) => ({ hashString: h })));
 
           // Don't spatially constrain the search if the geohahes covers the world
           // or if there are no geohashes
-          if (geohashes.coversEarth() || geohashes.length === 0) {
+          if (geohashes.length === 0 || geohashes.coversEarth()) {
             return "";
           }
 
-          // TODO: we may still want this option for when spatial filters are
-          // built other than with the current view extent from the map.
-          // geohashes = geohashes.consolidate();
+          if (consolidate) geohashes = geohashes.consolidate();
 
           const precisions = geohashes.getPrecisions();
 

src/js/models/maps/AssetColor.js

@@ -146,6 +146,7 @@ define(
          * Converts an 6 to 8 digit hex color value to RGBA values between 0 and 1
          * @param {string} hex - A hex color code, e.g. '#44A96A' or '#44A96A88'
          * @return {Color} - The RGBA values of the color
+         * @since x.x.x
          */
         hexToRGBA: function (hex) {
           var result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})?$/i.exec(hex);

src/js/models/maps/Map.js

@@ -339,6 +339,7 @@ define([
        * Reset the layers to the default layers. This will set a new MapAssets
        * collection on the layer attribute.
        * @returns {MapAssets} The new layers collection.
+       * @since x.x.x
        */
       resetLayers: function () {
         const newLayers = this.defaults()?.layers || new MapAssets();

src/js/models/maps/assets/Cesium3DTileset.js

@@ -335,6 +335,7 @@ define(
          * Return the label for a feature from a Cesium 3D tileset
          * @param {Cesium.Cesium3DTileFeature} feature A Cesium 3D Tile feature
          * @returns {string} The label
+         * @since x.x.x
          */
         getLabelFromFeature: function (feature) {
           if (!this.usesFeatureType(feature)) return null
@@ -345,6 +346,7 @@ define(
          * Return the Cesium3DTileset model for a feature from a Cesium 3D tileset
          * @param {Cesium.Cesium3DTileFeature} feature A Cesium 3D Tile feature
          * @returns {Cesium3DTileset} The model
+         * @since x.x.x
          */
         getCesiumModelFromFeature: function (feature) {
           if (!this.usesFeatureType(feature)) return null
@@ -355,6 +357,7 @@ define(
          * Return the ID used by Cesium for a feature from a Cesium 3D tileset
          * @param {Cesium.Cesium3DTileFeature} feature A Cesium 3D Tile feature
          * @returns {string} The ID
+         * @since x.x.x
          */
         getIDFromFeature: function (feature) {
           if (!this.usesFeatureType(feature)) return null

src/js/models/maps/assets/CesiumGeohash.js

@@ -117,14 +117,17 @@ define([
       /**
        * Get the property that we want the geohashes to display, e.g. count.
        * @returns {string} The property of interest.
+       * @since x.x.x
        */
       getPropertyOfInterest: function () {
         return this.get("colorPalette")?.get("property");
       },
 
       /**
        * For the property of interest (e.g. count) Get the min and max values
-       * from the geohashes collection and update the color palette. These
+       * from the geohashes collection and update the color palette.
+       * @since x.x.x
+       * 
        */
       updateColorRangeValues: function () {
         const colorPalette = this.get("colorPalette");
@@ -145,6 +148,7 @@ define([
        * Required that a mapModel be set on the model. If one is not set, then
        * the minimum precision from the geohash collection will be returned.
        * @returns {number} The precision level.
+       * @since x.x.x
        */
       getPrecision: function () {
         const limit = this.get("maxGeoHashes");
@@ -159,13 +163,15 @@ define([
        * set.
        * @param {Geohash[]|Object[]} geohashes The new set of geohash models to
        * display or attributes for the new geohash models.
+       * @since x.x.x
        */
       replaceGeohashes: function (geohashes) {
         this.get("geohashes").reset(geohashes);
       },
 
       /**
        * Stop the model from listening to itself for changes.
+       * @since x.x.x
        */
       stopListeners: function () {
         this.stopListening(this.get("geohashes"), "add remove update reset");
@@ -174,6 +180,7 @@ define([
       /**
        * Update and re-render the geohashes when the collection of geohashes
        * changes.
+       * @since x.x.x
        */
       startListening: function () {
         try {
@@ -199,7 +206,7 @@ define([
        * to those that are within the current map extent.
        * @returns {Geohashes} The geohashes to display.
        */
-      getGeohashes(limitToExtent = true) {
+      getGeohashes: function(limitToExtent = true) {
         let geohashes = this.get("geohashes");
         if (limitToExtent) {
           geohashes = this.getGeohashesForExtent();
@@ -210,6 +217,7 @@ define([
       /**
        * Get the geohashes that are currently in the map's extent.
        * @returns {Geohashes} The geohashes in the current extent.
+       * @since x.x.x
        */
       getGeohashesForExtent: function () {
         const extent = this.get("mapModel")?.get("currentViewExtent");
@@ -223,6 +231,7 @@ define([
        * @param {Boolean} [limitToExtent = true] - Set to false to return the
        * GeoJSON for all geohashes, not just those in the current extent.
        * @returns {Object} The GeoJSON representation of the geohashes.
+       * @since x.x.x
        */
       getGeoJSON: function (limitToExtent = true) {
         const geohashes = this.getGeohashes(limitToExtent);
@@ -234,6 +243,7 @@ define([
        * @param {Boolean} [limitToExtent = true] - Set to false to return the
        * CZML for all geohashes, not just those in the current extent.
        * @returns {Object} The CZML representation of the geohashes.
+       * @since x.x.x
        */
       getCZML: function (limitToExtent = true) {
         const geohashes = this.getGeohashes(limitToExtent);
@@ -276,6 +286,7 @@ define([
        * Find the geohash Entity on the map and add it to the selected
        * features.
        * @param {string} geohash The geohash to select.
+       * @since x.x.x
        */
       selectGeohashes: function (geohashes) {
         const toSelect = [...new Set(geohashes.map((geohash) => {

src/js/models/maps/assets/CesiumVectorData.js

@@ -270,6 +270,7 @@ define(
          * returns an object that may or may not be an Entity.
          * @param {Object} mapObject - An object returned from the Cesium map
          * @returns {Cesium.Entity} - The Entity object if found, otherwise null.
+         * @since x.x.x
          */
         getEntityFromMapObject(mapObject) {
           const entityType = this.get("featureType")
@@ -289,6 +290,7 @@ define(
 
         /**
          * @inheritdoc
+         * @since x.x.x
          */
         usesFeatureType: function (feature) {
           // This method could be passed the entity directly, or the object

src/js/models/maps/assets/MapAsset.js

@@ -403,6 +403,7 @@ define(
          * @param {Cesium.Cesium3DTilesetFeature|Cesium.Entity} feature 
          * @returns {boolean} true if the feature is an instance of the feature
          * type set on the asset model, false otherwise.
+         * @since x.x.x
          */
         usesFeatureType: function(feature) {
           const ft = this.get("featureType");
@@ -419,6 +420,7 @@ define(
          * in the map, e.g. a Cesium.Entity or a Cesium.Cesium3DTileFeature
          * @returns {boolean} Returns true if the given feature is part of the
          * selectedFeatures collection in this asset
+         * @since x.x.x
          */
         containsFeature: function (feature) {
           if (!this.usesFeatureType(feature)) return false

src/js/views/search/CatalogSearchView.js

@@ -321,6 +321,7 @@ define([
 
       /**
        * Indicates that there was a problem rendering this view.
+       * @since x.x.x
        */
       renderError: function () {
         this.$el.html(this.errorTemplate);
@@ -735,6 +736,7 @@ define([
       /**
        * Change the content of the map toggle label to indicate whether
        * clicking the button will show or hide the map.
+       * @since x.x.x
        */
       updateToggleMapLabel: function () {
         try {
@@ -766,6 +768,7 @@ define([
       /**
        * Change the content of the filters toggle label to indicate whether
        * clicking the button will show or hide the filters.
+       * @since x.x.x
        */
       updateToggleFiltersLabel: function () {
         try {
@@ -805,6 +808,7 @@ define([
        * to switch to. true = limit search to map area, false = do not limit
        * search to map area. If not provided, the opposite of the current mode
        * will be used.
+       * @since x.x.x
        */
       toggleMapFilter: function (newSetting) {
         // Make sure the new setting is a boolean

src/js/views/search/SearchResultsView.js

@@ -73,8 +73,10 @@ define([
 
           this.startListening();
         } catch (e) {
-          console.log("Failed to render the search results: ", e);
-          // TODO: Add error handling
+          console.log("Failed to render search results view.", e);
+          const emailMsg =
+            "There was an error rendering the search results view. " + e;
+          this.showError(null, { responseText: emailMsg });
         }
       },
 

src/js/views/search/SorterView.js

@@ -80,6 +80,10 @@ define(["backbone"], function (Backbone) {
         this.el.replaceChildren(select);
       },
 
+      /**
+       * Hides the view if there are no search results.
+       * @since x.x.x
+       */
       hideIfNoResults: function () {
         if (
           !this.searchResults ||

test/js/specs/unit/models/connectors/Map-Search.spec.js

@@ -68,20 +68,5 @@ define([
       });
     });
 
-    describe("Total Number of Results", function () {
-      it("should get the total number of results", function () {
-        expect(this.mapSearch.getTotalNumberOfResults() === null);
-      });
-
-      it("should get the total number of results", function () {
-        var searchResults = {
-          getNumFound: function () {
-            return 10;
-          },
-        };
-        this.mapSearch.set("searchResults", searchResults);
-        this.mapSearch.getTotalNumberOfResults().should.equal(10);
-      });
-    });
   });
 });