Style checks and more jsdoc.

lib/utils.js

@@ -1,7 +1,12 @@
 "use strict";
 
 
-// avoiding deps on jquery and co
+/**
+ * Encode a dictionary of query parameters.
+ * @param {Object} params A dict of key/values to encode e.g.
+ * {"foo": "bar", "baz": "taz"}
+ * @return {string} The encoded string e.g. foo=bar&baz=taz
+ */
 module.exports.encodeParams = function(params) {
     var qs = "";
     for (var key in params) {
@@ -12,6 +17,14 @@ module.exports.encodeParams = function(params) {
     return qs.substring(1);
 };
 
+/**
+ * Encodes a URI according to a set of template variables. Variables will be
+ * passed through encodeURIComponent.
+ * @param {string} pathTemplate The path with template variables e.g. '/foo/$bar'.
+ * @param {Object} variables The key/value pairs to replace the template
+ * variables with. E.g. { "$bar": "baz" }.
+ * @return {string} The result of replacing all template variables e.g. '/foo/baz'.
+ */
 module.exports.encodeUri = function(pathTemplate, variables) {
     for (var key in variables) {
         if (!variables.hasOwnProperty(key)) { continue; }
@@ -22,6 +35,13 @@ module.exports.encodeUri = function(pathTemplate, variables) {
     return pathTemplate;
 };
 
+/**
+ * Applies a map function to the given array.
+ * @param {Array} array The array to apply the function to.
+ * @param {Function} fn The function that will be invoked for each element in
+ * the array.
+ * @return {Array} A new array with the results of the function.
+ */
 module.exports.map = function(array, fn) {
     var results = new Array(array.length);
     for (var i = 0; i < array.length; i++) {
@@ -30,23 +50,40 @@ module.exports.map = function(array, fn) {
     return results;
 };
 
+/**
+ * Checks if the given thing is a function.
+ * @param {*} value The thing to check.
+ * @return {boolean} True if it is a function.
+ */
 module.exports.isFunction = function(value) {
     return Object.prototype.toString.call(value) == "[object Function]";
 };
 
+/**
+ * Checks that the given object has the specified keys.
+ * @param {Object} obj The object to check.
+ * @param {string[]} keys The list of keys that 'obj' must have.
+ * @throws If the object is missing keys.
+ */
 module.exports.checkObjectHasKeys = function(obj, keys) {
     for (var i = 0; i < keys.length; i++) {
         if (!obj.hasOwnProperty(keys[i])) {
-            throw new Error("Missing required key: "+keys[i]);
+            throw new Error("Missing required key: " + keys[i]);
         }
     }
 };
 
+/**
+ * Checks that the given object has no extra keys other than the specified ones.
+ * @param {Object} obj The object to check.
+ * @param {string[]} allowedKeys The list of allowed key names.
+ * @throws If there are extra keys.
+ */
 module.exports.checkObjectHasNoAdditionalKeys = function(obj, allowedKeys) {
     for (var key in obj) {
         if (!obj.hasOwnProperty(key)) { continue; }
         if (allowedKeys.indexOf(key) === -1) {
-            throw new Error("Unknown key: "+key);
+            throw new Error("Unknown key: " + key);
         }
     }
-};
+};