Add docs for mock-request.HttpBackend to make it less magical.

spec/mock-request.js

@@ -1,9 +1,14 @@
 "use strict";
 
+/**
+ * This is a mock framework for an HTTP backend, heavily inspired by Angular.js
+ */
+
 function HttpBackend() {
     this.requests = [];
     this.expectedRequests = [];
     var self = this;
+    // the request function dependency that the SDK needs.
     this.requestFn = function(opts, callback) {
         var realReq = new Request(opts.method, opts.uri, opts.body, opts.qs);
         realReq.callback = callback;
@@ -11,6 +16,9 @@ function HttpBackend() {
     };
 }
 HttpBackend.prototype = {
+    /**
+     * Respond to all of the requests (flush the queue).
+     */
     flush: function() {
         // if there's more real requests and more expected requests, flush 'em.
         while(this.requests.length > 0 && this.expectedRequests.length > 0) {
@@ -42,6 +50,10 @@ HttpBackend.prototype = {
             }
         }
     },
+
+    /**
+     * Makes sure that the SDK hasn't sent any more requests to the backend.
+     */
     verifyNoOutstandingRequests: function() {
         var firstOutstandingReq = this.requests[0] || {};
         expect(this.requests.length).toEqual(0,
@@ -49,12 +61,24 @@ HttpBackend.prototype = {
             firstOutstandingReq.path
         );
     },
+
+    /**
+     * Makes sure that the test doesn't have any unresolved requests.
+     */
     verifyNoOutstandingExpectation: function() {
         var firstOutstandingExpectation = this.expectedRequests[0] || {};
         expect(this.expectedRequests.length).toEqual(0,
             "Expected to see HTTP request for "+firstOutstandingExpectation.path
         );
     },
+
+    /**
+     * Create an expected request.
+     * @param {string} method The HTTP method
+     * @param {string} path The path (which can be partial)
+     * @param {Object} data The expected data.
+     * @return {Request} An expected request.
+     */
     when: function(method, path, data) {
         var pendingReq = new Request(method, path, data);
         this.expectedRequests.push(pendingReq);
@@ -72,10 +96,21 @@ function Request(method, path, data, queryParams) {
     this.checks = [];
 }
 Request.prototype = {
+    /**
+     * Execute a check when this request has been satisfied.
+     * @param {Function} fn The function to execute.
+     * @return {Request} for chaining calls.
+     */
     check: function(fn) {
         this.checks.push(fn);
         return this;
     },
+
+    /**
+     * Respond with the given data when this request is satisfied.
+     * @param {Number} code The HTTP status code.
+     * @param {Object} data The HTTP JSON body.
+     */
     respond: function(code, data) {
         this.response = {
             response: {
@@ -86,6 +121,12 @@ Request.prototype = {
             err: null
         };
     },
+
+    /**
+     * Fail with an Error when this request is satisfied.
+     * @param {Number} code The HTTP status code.
+     * @param {Error} err The error to throw (e.g. Network Error)
+     */
     fail: function(code, err) {
         this.response = {
             response: {