More jsdoc

lib/client.js

@@ -62,7 +62,7 @@ module.exports.MatrixClient.prototype = {
      * @param {module:client.callback} callback Optional.
      * @return {module:client.Promise} Resolves: <code>{room_id: {string}, 
      * room_alias: {string(opt)}}</code>
-     * @return {module:http-api.MatrixError} Rejects: with the error response.
+     * @return {module:http-api.MatrixError} Rejects: with an error response.
      */
     createRoom: function(options, callback) {
         // valid options include: room_alias_name, visibility, invite
@@ -71,6 +71,13 @@ module.exports.MatrixClient.prototype = {
         );
     },
 
+    /**
+     * Join a room.
+     * @param {string} roomIdOrAlias The room ID or room alias to join.
+     * @param {module:client.callback} callback Optional.
+     * @return {module:client.Promise} Resolves: <code>{room_id: {string}}</code>
+     * @return {module:http-api.MatrixError} Rejects: with an error response.
+     */
     joinRoom: function(roomIdOrAlias, callback) {
         var path = utils.encodeUri("/join/$roomid", { $roomid: roomIdOrAlias});
         return this._http.authedRequest(callback, "POST", path, undefined, {});

lib/http-api.js

@@ -51,6 +51,15 @@ module.exports.MatrixHttpApi.prototype = {
     // URI functions
     // =============
 
+    /**
+     * Get the HTTP URL for an MXC URI.
+     * @param {string} mxc The mxc:// URI.
+     * @param {Number} width The desired width of the thumbnail.
+     * @param {Number} height The desired height of the thumbnail.
+     * @param {string} resizeMethod The thumbnail resize method to use, either
+     * "crop" or "scale".
+     * @return {string} The complete URL to the content.
+     */
     getHttpUriForMxc: function(mxc, width, height, resizeMethod) {
         if (typeof mxc !== "string" || !mxc) {
             return mxc;
@@ -88,6 +97,13 @@ module.exports.MatrixHttpApi.prototype = {
             ("?" + utils.encodeParams(params))) + fragment;
     },
 
+    /**
+     * Get an identicon URL from an arbitrary string.
+     * @param {string} identiconString The string to create an identicon for.
+     * @param {Number} width The desired width of the image in pixels.
+     * @param {Number} height The desired height of the image in pixels.
+     * @return {string} The complete URL to the identicon.
+     */
     getIdenticonUri: function(identiconString, width, height) {
         if (!identiconString) {
             return;
@@ -123,18 +139,73 @@ module.exports.MatrixHttpApi.prototype = {
         };
     },
 
+    /**
+     * Perform an authorised request to the homeserver.
+     * @param {Function} callback Optional. The callback to invoke on
+     * success/failure. See the promise return values for more information.
+     * @param {string} method The HTTP method e.g. "GET".
+     * @param {string} path The HTTP path <b>after</b> the supplied prefix e.g.
+     * "/createRoom".
+     * @param {Object} queryParams A dict of query params (these will NOT be
+     * urlencoded).
+     * @param {Object} data The HTTP JSON body.
+     * @return {module:client.Promise} Resolves to <code>{data: {Object},
+     * headers: {Object}, code: {Number}}</code>.
+     * If <code>onlyData</code> is set, this will resolve to the <code>data</code>
+     * object only.
+     * @return {module:http-api.MatrixError} Rejects with an error if a problem
+     * occurred. This includes network problems and Matrix-specific error JSON.
+     */
     authedRequest: function(callback, method, path, queryParams, data) {
         if (!queryParams) { queryParams = {}; }
         queryParams.access_token = this.opts.accessToken;
         return this.request(callback, method, path, queryParams, data);
     },
 
+    /**
+     * Perform a request to the homeserver without any credentials.
+     * @param {Function} callback Optional. The callback to invoke on
+     * success/failure. See the promise return values for more information.
+     * @param {string} method The HTTP method e.g. "GET".
+     * @param {string} path The HTTP path <b>after</b> the supplied prefix e.g.
+     * "/createRoom".
+     * @param {Object} queryParams A dict of query params (these will NOT be
+     * urlencoded).
+     * @param {Object} data The HTTP JSON body.
+     * @return {module:client.Promise} Resolves to <code>{data: {Object},
+     * headers: {Object}, code: {Number}}</code>.
+     * If <code>onlyData</code> is set, this will resolve to the <code>data</code>
+     * object only.
+     * @return {module:http-api.MatrixError} Rejects with an error if a problem
+     * occurred. This includes network problems and Matrix-specific error JSON.
+     */
     request: function(callback, method, path, queryParams, data) {
         return this.requestWithPrefix(
             callback, method, path, queryParams, data, this.opts.prefix
         );
     },
 
+    /**
+     * Perform an authorised request to the homeserver with a specific path
+     * prefix which overrides the default for this call only. Useful for hitting
+     * different Matrix Client-Server versions.
+     * @param {Function} callback Optional. The callback to invoke on
+     * success/failure. See the promise return values for more information.
+     * @param {string} method The HTTP method e.g. "GET".
+     * @param {string} path The HTTP path <b>after</b> the supplied prefix e.g.
+     * "/createRoom".
+     * @param {Object} queryParams A dict of query params (these will NOT be
+     * urlencoded).
+     * @param {Object} data The HTTP JSON body.
+     * @param {string} prefix The full prefix to use e.g.
+     * "/_matrix/client/v2_alpha".
+     * @return {module:client.Promise} Resolves to <code>{data: {Object},
+     * headers: {Object}, code: {Number}}</code>.
+     * If <code>onlyData</code> is set, this will resolve to the <code>data</code>
+     * object only.
+     * @return {module:http-api.MatrixError} Rejects with an error if a problem
+     * occurred. This includes network problems and Matrix-specific error JSON.
+     */
     authedRequestWithPrefix: function(callback, method, path, queryParams, data,
                                       prefix) {
         var fullUri = this.opts.baseUrl + prefix + path;
@@ -145,6 +216,27 @@ module.exports.MatrixHttpApi.prototype = {
         return this._request(callback, method, fullUri, queryParams, data);
     },
 
+    /**
+     * Perform a request to the homeserver without any credentials but with a
+     * specific path prefix which overrides the default for this call only.
+     * Useful for hitting different Matrix Client-Server versions.
+     * @param {Function} callback Optional. The callback to invoke on
+     * success/failure. See the promise return values for more information.
+     * @param {string} method The HTTP method e.g. "GET".
+     * @param {string} path The HTTP path <b>after</b> the supplied prefix e.g.
+     * "/createRoom".
+     * @param {Object} queryParams A dict of query params (these will NOT be
+     * urlencoded).
+     * @param {Object} data The HTTP JSON body.
+     * @param {string} prefix The full prefix to use e.g.
+     * "/_matrix/client/v2_alpha".
+     * @return {module:client.Promise} Resolves to <code>{data: {Object},
+     * headers: {Object}, code: {Number}}</code>.
+     * If <code>onlyData</code> is set, this will resolve to the <code>data</code>
+     * object only.
+     * @return {module:http-api.MatrixError} Rejects with an error if a problem
+     * occurred. This includes network problems and Matrix-specific error JSON.
+     */
     requestWithPrefix: function(callback, method, path, queryParams, data, prefix) {
         var fullUri = this.opts.baseUrl + prefix + path;
         if (!queryParams) {