Merge pull request #48 from firebase/jw-cleanup

Miscellaneous cleanup

src/geoCallbackRegistration.js

@@ -3,7 +3,7 @@
  *
  * @constructor
  * @this {GeoCallbackRegistration}
- * @param {function} cancelCallback Callback to run when this callback registration is cancelled.
+ * @callback cancelCallback Callback to run when this callback registration is cancelled.
  */
 var GeoCallbackRegistration = function(cancelCallback) {
   /********************/

src/geoFire.js

@@ -24,8 +24,8 @@ var GeoFire = function(firebaseRef) {
    * If the provided key already exists in this GeoFire, it will be overwritten with the new location value.
    *
    * @param {string} key The key representing the location to add.
-   * @param {array} location The [latitude, longitude] pair to add.
-   * @return {RSVP.Promise} A promise that is fulfilled when the write is complete.
+   * @param {Array.<number>} location The [latitude, longitude] pair to add.
+   * @return {Promise.<>} A promise that is fulfilled when the write is complete.
    */
   this.set = function(key, location) {
     validateKey(key);
@@ -57,7 +57,7 @@ var GeoFire = function(firebaseRef) {
    * If the provided key does not exist, the returned promise is fulfilled with null.
    *
    * @param {string} key The key of the location to retrieve.
-   * @return {RSVP.Promise} A promise that is fulfilled with the location of the given key.
+   * @return {Promise.<Array.<number>>} A promise that is fulfilled with the location of the given key.
    */
   this.get = function(key) {
     validateKey(key);
@@ -80,7 +80,7 @@ var GeoFire = function(firebaseRef) {
    * If the provided key is not in this GeoFire, the promise will still successfully resolve.
    *
    * @param {string} key The key of the location to remove.
-   * @return {RSVP.Promise} A promise that is fulfilled after the inputted key is removed.
+   * @return {Promise.<string>} A promise that is fulfilled after the inputted key is removed.
    */
   this.remove = function(key) {
     return this.set(key, null);
@@ -89,7 +89,7 @@ var GeoFire = function(firebaseRef) {
   /**
    * Returns a new GeoQuery instance with the provided queryCriteria.
    *
-   * @param {object} queryCriteria The criteria which specifies the GeoQuery's center and radius.
+   * @param {Object} queryCriteria The criteria which specifies the GeoQuery's center and radius.
    * @return {GeoQuery} A new GeoQuery object.
    */
   this.query = function(queryCriteria) {
@@ -111,8 +111,8 @@ var GeoFire = function(firebaseRef) {
  * via the Haversine formula. Note that this is approximate due to the fact that the
  * Earth's radius varies between 6356.752 km and 6378.137 km.
  *
- * @param {array} location1 The [latitude, longitude] pair of the first location.
- * @param {array} location2 The [latitude, longitude] pair of the second location.
+ * @param {Array.<number>} location1 The [latitude, longitude] pair of the first location.
+ * @param {Array.<number>} location2 The [latitude, longitude] pair of the second location.
  * @return {number} The distance, in kilometers, between the inputted locations.
  */
 GeoFire.distance = function(location1, location2) {

src/geoFireUtils.js

@@ -65,7 +65,7 @@ var validateKey = function(key) {
 /**
  * Validates the inputted location and throws an error if it is invalid.
  *
- * @param {array} location The [latitude, longitude] pair to be verified.
+ * @param {Array.<number>} location The [latitude, longitude] pair to be verified.
  */
 var validateLocation = function(location) {
   var error;
@@ -129,7 +129,7 @@ var validateGeohash = function(geohash) {
 /**
  * Validates the inputted query criteria and throws an error if it is invalid.
  *
- * @param {object} newQueryCriteria The criteria which specifies the query's center and/or radius.
+ * @param {Object} newQueryCriteria The criteria which specifies the query's center and/or radius.
  */
 var validateCriteria = function(newQueryCriteria, requireCenterAndRadius) {
   if (typeof newQueryCriteria !== "object") {
@@ -182,13 +182,12 @@ var degreesToRadians = function(degrees) {
 };
 
 /**
- * Generates a geohash of the specified precision/string length
- * from the [latitude, longitude] pair, specified as an array.
+ * Generates a geohash of the specified precision/string length from the  [latitude, longitude]
+ * pair, specified as an array.
  *
- * @param {array} location The [latitude, longitude] pair to encode into
- * a geohash.
- * @param {number} precision The length of the geohash to create. If no
- * precision is specified, the global default is used.
+ * @param {Array.<number>} location The [latitude, longitude] pair to encode into a geohash.
+ * @param {number=} precision The length of the geohash to create. If no precision is
+ * specified, the global default is used.
  * @return {string} The geohash of the inputted location.
  */
 var encodeGeohash = function(location, precision) {
@@ -255,10 +254,11 @@ var encodeGeohash = function(location, precision) {
 };
 
 /**
- * Calculates the number of degrees a given distance is at a given latitude
- * @param {number} distance
- * @param {number} latitude
- * @return {number} The number of degrees the distance corresponds to
+ * Calculates the number of degrees a given distance is at a given latitude.
+ *
+ * @param {number} distance The distance to convert.
+ * @param {number} latitude The latitude at which to calculate.
+ * @return {number} The number of degrees the distance corresponds to.
  */
 var metersToLongitudeDegrees = function(distance, latitude) {
   var radians = degreesToRadians(latitude);
@@ -274,30 +274,32 @@ var metersToLongitudeDegrees = function(distance, latitude) {
 };
 
 /**
- * Calculates the bits necessary to reach a given resolution in meters for
- * the longitude at a given latitude
- * @param {number} resolution
- * @param {number} latitude
- * @return {number}
+ * Calculates the bits necessary to reach a given resolution, in meters, for the longitude at a
+ * given latitude.
+ *
+ * @param {number} resolution The desired resolution.
+ * @param {number} latitude The latitude used in the conversion.
+ * @return {number} The bits necessary to reach a given resolution, in meters.
  */
 var longitudeBitsForResolution = function(resolution, latitude) {
   var degs = metersToLongitudeDegrees(resolution, latitude);
   return (Math.abs(degs) > 0.000001) ?  Math.max(1, Math.log2(360/degs)) : 1;
 };
 
 /**
- * Calculates the bits necessary to reach a given resolution in meters for
- * the latitude
- * @param {number} resolution
+ * Calculates the bits necessary to reach a given resolution, in meters, for the latitude.
+ *
+ * @param {number} resolution The bits necessary to reach a given resolution, in meters.
  */
 var latitudeBitsForResolution = function(resolution) {
   return Math.min(Math.log2(g_EARTH_MERI_CIRCUMFERENCE/2/resolution), g_MAXIMUM_BITS_PRECISION);
 };
 
 /**
- * Wraps the longitude to [-180,180]
- * @param {number} longitude
- * @return {number} longitude
+ * Wraps the longitude to [-180,180].
+ *
+ * @param {number} longitude The longitude to wrap.
+ * @return {number} longitude The resulting longitude.
  */
 var wrapLongitude = function(longitude) {
   if (longitude <= 180 && longitude >= -180) {
@@ -313,12 +315,12 @@ var wrapLongitude = function(longitude) {
 };
 
 /**
- * Calculates the maximum number of bits of a geohash to get
- * a bounding box that is larger than a given size at the given
- * coordinate.
- * @param {array} coordinate The coordinate as a [latitude, longitude] pair
- * @param {number} size The size of the bounding box
- * @return {number} The number of bits necessary for the geohash
+ * Calculates the maximum number of bits of a geohash to get a bounding box that is larger than a
+ * given size at the given coordinate.
+ *
+ * @param {Array.<number>} coordinate The coordinate as a [latitude, longitude] pair.
+ * @param {number} size The size of the bounding box.
+ * @return {number} The number of bits necessary for the geohash.
  */
 var boundingBoxBits = function(coordinate, size) {
   var latDeltaDegrees = size/g_METERS_PER_DEGREE_LATITUDE;
@@ -331,13 +333,13 @@ var boundingBoxBits = function(coordinate, size) {
 };
 
 /**
- * Calculates 8 points on the bounding box and the center of a given circle.
- * At least one geohash of these 9 coordinates, truncated to a precision of
- * at most radius, are guaranteed to be prefixes of any geohash that lies
- * within the circle.
- * @param {array} center The center given as [latitude, longitude]
- * @param {number} radius The radius of the circle
- * @return {number} The four bounding box points
+ * Calculates eight points on the bounding box and the center of a given circle. At least one
+ * geohash of these nine coordinates, truncated to a precision of at most radius, are guaranteed
+ * to be prefixes of any geohash that lies within the circle.
+ *
+ * @param {Array.<number>} center The center given as [latitude, longitude].
+ * @param {number} radius The radius of the circle.
+ * @return {Array.<Array.<number>>} The eight bounding box points.
  */
 var boundingBoxCoordinates = function(center, radius) {
   var latDegrees = radius/g_METERS_PER_DEGREE_LATITUDE;
@@ -360,10 +362,11 @@ var boundingBoxCoordinates = function(center, radius) {
 };
 
 /**
- * Calculates the bounding box query for a geohash with x bits precision
- * @param {string} geohash
- * @param {number} bits
- * @return {array} A [start,end] pair
+ * Calculates the bounding box query for a geohash with x bits precision.
+ *
+ * @param {string} geohash The geohash whose bounding box query to generate.
+ * @param {number} bits The number of bits of precision.
+ * @return {Array.<string>} A [start, end] pair of geohashes.
  */
 var geohashQuery = function(geohash, bits) {
   validateGeohash(geohash);
@@ -393,12 +396,12 @@ var geohashQuery = function(geohash, bits) {
 };
 
 /**
- * Calculates a set of queries to fully contain a given circle
- * A query is a [start,end] pair where any geohash is guaranteed to
- * be lexiographically larger then start and smaller than end
- * @param {array} center The center given as [latitude, longitude] pair
- * @param {number} radius The radius of the circle
- * @return {array} An array of geohashes containing a [start,end] pair
+ * Calculates a set of queries to fully contain a given circle. A query is a [start, end] pair
+ * where any geohash is guaranteed to be lexiographically larger then start and smaller than end.
+ *
+ * @param {Array.<number>} center The center given as [latitude, longitude] pair.
+ * @param {number} radius The radius of the circle.
+ * @return {Array.<Array.<string>>} An array of geohashes containing a [start, end] pair.
  */
 var geohashQueries = function(center, radius) {
   validateLocation(center);
@@ -417,11 +420,11 @@ var geohashQueries = function(center, radius) {
 };
 
 /**
- * Encodes a location and geohash as a GeoFire object
+ * Encodes a location and geohash as a GeoFire object.
  *
- * @param {array} location The location as [latitude, longitude] pair.
- * @param {string} geohash The geohash of the location
- * @return {Object} The location encoded as GeoFire object
+ * @param {Array.<number>} location The location as [latitude, longitude] pair.
+ * @param {string} geohash The geohash of the location.
+ * @return {Object} The location encoded as GeoFire object.
  */
 function encodeGeoFireObject(location, geohash) {
   validateLocation(location);
@@ -433,10 +436,11 @@ function encodeGeoFireObject(location, geohash) {
 }
 
 /**
- * Decodes the location given as GeoFire object. Returns null if decoding fails
+ * Decodes the location given as GeoFire object. Returns null if decoding fails.
  *
- * @param {Object} geoFireObj The location encoded as GeoFire object
- * @return {array} location The location as [latitude, longitude] pair or null if decoding fails
+ * @param {Object} geoFireObj The location encoded as GeoFire object.
+ * @return {?Array.<number>} location The location as [latitude, longitude] pair or null if
+ * decoding fails.
  */
 function decodeGeoFireObject(geoFireObj) {
   if (geoFireObj !== null && geoFireObj.hasOwnProperty("l") && Array.isArray(geoFireObj.l) && geoFireObj.l.length === 2) {