Style checks and more jsdoc.

dist/browser-matrix-dev.js

@@ -22,7 +22,7 @@ function MatrixClient(opts) {
     utils.checkObjectHasNoAdditionalKeys(opts,
         ["baseUrl", "request", "usePromises", "accessToken", "userId", "store"]
     );
-    
+
     this.store = opts.store || null;
     // track our position in the overall eventstream
     this.fromToken = undefined;
@@ -308,7 +308,7 @@ MatrixClient.prototype = {
             'bind': bind
         };
         return this._http.authedRequestWithPrefix(
-            callback, "POST", path, qps, data, httpApi.PREFIX_V2_ALPHA
+            callback, "POST", path, null, data, httpApi.PREFIX_V2_ALPHA
         );
     },
 
@@ -464,7 +464,7 @@ MatrixClient.prototype = {
     },
 
     isLoggedIn: function() {
-        return this._http.opts.accessToken !== undefined
+        return this._http.opts.accessToken !== undefined;
     },
 
 
@@ -741,6 +741,7 @@ var HEADERS = {
 
 /**
  * Construct a MatrixHttpApi.
+ * @constructor
  * @param {Object} opts The options to use for this HTTP API.
  * @param {string} opts.baseUrl Required. The base client-server URL e.g.
  * 'http://localhost:8008'.
@@ -869,7 +870,7 @@ MatrixHttpApi.prototype = {
     _request: function(callback, method, uri, queryParams, data) {
         if (callback !== undefined && !utils.isFunction(callback)) {
             throw Error(
-                "Expected callback to be a function but got "+typeof callback
+                "Expected callback to be a function but got " + typeof callback
             );
         }
 
@@ -937,7 +938,7 @@ module.exports.request = function(r) {
     request = r;
 };
 
-/*
+/**
  * Construct a Matrix Client. Identical to {@link client/MatrixClient} except
  * the 'request' option is already specified.
  * @param {(Object|string)} opts The configuration options for this client. If
@@ -946,6 +947,7 @@ module.exports.request = function(r) {
  * @param {boolean} opts.usePromises True to use promises rather than callbacks.
  * @param {string} opts.accessToken The access_token for this user.
  * @param {string} opts.userId The user ID for this user.
+ * @return {MatrixClient} A new matrix client.
  */
 module.exports.createClient = function(opts) {
     if (typeof opts === "string") {
@@ -1166,7 +1168,12 @@ module.exports = MatrixInMemoryStore;
 "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) {
@@ -1177,6 +1184,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; }
@@ -1187,6 +1202,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++) {
@@ -1195,26 +1217,44 @@ 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);
         }
     }
 };
+
 },{}],7:[function(require,module,exports){
 // Browser Request
 //

lib/client.js

@@ -21,7 +21,7 @@ function MatrixClient(opts) {
     utils.checkObjectHasNoAdditionalKeys(opts,
         ["baseUrl", "request", "usePromises", "accessToken", "userId", "store"]
     );
-    
+
     this.store = opts.store || null;
     // track our position in the overall eventstream
     this.fromToken = undefined;
@@ -307,7 +307,7 @@ MatrixClient.prototype = {
             'bind': bind
         };
         return this._http.authedRequestWithPrefix(
-            callback, "POST", path, qps, data, httpApi.PREFIX_V2_ALPHA
+            callback, "POST", path, null, data, httpApi.PREFIX_V2_ALPHA
         );
     },
 
@@ -463,7 +463,7 @@ MatrixClient.prototype = {
     },
 
     isLoggedIn: function() {
-        return this._http.opts.accessToken !== undefined
+        return this._http.opts.accessToken !== undefined;
     },
 
 

lib/http-api.js

@@ -26,6 +26,7 @@ var HEADERS = {
 
 /**
  * Construct a MatrixHttpApi.
+ * @constructor
  * @param {Object} opts The options to use for this HTTP API.
  * @param {string} opts.baseUrl Required. The base client-server URL e.g.
  * 'http://localhost:8008'.
@@ -154,7 +155,7 @@ MatrixHttpApi.prototype = {
     _request: function(callback, method, uri, queryParams, data) {
         if (callback !== undefined && !utils.isFunction(callback)) {
             throw Error(
-                "Expected callback to be a function but got "+typeof callback
+                "Expected callback to be a function but got " + typeof callback
             );
         }
 

lib/matrix.js

@@ -20,7 +20,7 @@ module.exports.request = function(r) {
     request = r;
 };
 
-/*
+/**
  * Construct a Matrix Client. Identical to {@link client/MatrixClient} except
  * the 'request' option is already specified.
  * @param {(Object|string)} opts The configuration options for this client. If
@@ -29,6 +29,7 @@ module.exports.request = function(r) {
  * @param {boolean} opts.usePromises True to use promises rather than callbacks.
  * @param {string} opts.accessToken The access_token for this user.
  * @param {string} opts.userId The user ID for this user.
+ * @return {MatrixClient} A new matrix client.
  */
 module.exports.createClient = function(opts) {
     if (typeof opts === "string") {

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);
         }
     }
-};
+};