doc(angular.mock.service.$browser): add xhr docs

src/angular-mocks.js

@@ -69,8 +69,8 @@
  * Built-in mocks:
  *
  * * {@link angular.mock.service.$browser $browser } - A mock implementation of the browser.
- * * {@link angular.mock.service.$exceptionHandler $exceptionHandler } - A mock implementation of the
- * angular service exception handler.
+ * * {@link angular.mock.service.$exceptionHandler $exceptionHandler } - A mock implementation of
+ *   the angular service exception handler.
  * * {@link angular.mock.service.$log $log } - A mock implementation of the angular service log.
  */
 angular.mock = {};
@@ -80,6 +80,24 @@ angular.mock = {};
  * @workInProgress
  * @ngdoc service
  * @name angular.mock.service.$browser
+ *
+ * @description
+ * This service is a mock implementation of {@link angular.service.$browser}. It provides fake
+ * implementation for commonly used browser apis that are hard to test, e.g. setTimeout, xhr,
+ * cookies.
+ *
+ * This implementation is automatically available and replaces regular `$browser` service in tests
+ * when `angular-mocks.js` is loaded.
+ *
+ * The api of this service is the same as the real {@link angular.service.$browser $browser}, except
+ * that there are several helper methods available which can be used in tests.
+ *
+ * The following apis can be used in tests:
+ *
+ * - {@link angular.mock.service.$browser.xhr $browser.xhr} — enables testing of code that uses
+ *   the {@link angular.service.$xhr $xhr service} to make XmlHttpRequests.
+ * - $browser.defer — enables testing of code that uses
+ *   {@link angular.service.$defer $defer service} for executing functions via the `setTimeout` api.
  */
 function MockBrowser() {
   var self = this,
@@ -108,6 +126,33 @@ function MockBrowser() {
   };
 
 
+  /**
+    * @ngdoc function
+    * @name angular.mock.service.$browser.xhr
+    *
+    * @description
+    * Generic method for training browser to expect a request in a test and respond to it.
+    *
+    * See also convenience methods for browser training:
+    *
+    * - {@link angular.mock.service.$browser.xhr.expectGET $browser.xhr.expectGET}
+    * - {@link angular.mock.service.$browser.xhr.expectPOST $browser.xhr.expectPOST}
+    * - {@link angular.mock.service.$browser.xhr.expectPUT $browser.xhr.expectPUT}
+    * - {@link angular.mock.service.$browser.xhr.expectDELETE $browser.xhr.expectDELETE}
+    * - {@link angular.mock.service.$browser.xhr.expectJSON $browser.xhr.expectJSON}
+    *
+    * To flush pending requests in tests use
+    * {@link angular.mock.service.$browser.xhr.flush $browser.xhr.flush}.
+    *
+    * @param {string} method Expected HTTP method.
+    * @param {string} url Url path for which a request is expected.
+    * @param {(object|string)=} data Expected body of the (POST) HTTP request.
+    * @param {function(number, *)} callback Callback to call when response is flushed.
+    * @param {object} headers Key-value pairs of expected headers.
+    * @returns {object} Response configuration object. You can call its `respond()` method to
+    *   configure what should the browser mock return when the response is
+    *   {@link angular.mock.service.$browser.xhr.flush flushed}.
+    */
   self.xhr = function(method, url, data, callback, headers) {
     headers = headers || {};
     if (data && angular.isObject(data)) data = angular.toJson(data);
@@ -142,11 +187,85 @@ function MockBrowser() {
       }
     };
   };
+
+  /**
+    * @ngdoc function
+    * @name angular.mock.service.$browser.xhr.expectGET
+    *
+    * @description
+    * Trains browser to expect a `GET` request and respond to it.
+    *
+    * @param {string} url Url path for which a request is expected.
+    * @returns {object} Response configuration object. You can call its `respond()` method to
+    *   configure what should the browser mock return when the response is
+    *   {@link angular.mock.service.$browser.xhr.flush flushed}.
+    */
   self.xhr.expectGET    = angular.bind(self, self.xhr.expect, 'GET');
+
+  /**
+    * @ngdoc function
+    * @name angular.mock.service.$browser.xhr.expectPOST
+    *
+    * @description
+    * Trains browser to expect a `POST` request and respond to it.
+    *
+    * @param {string} url Url path for which a request is expected.
+    * @returns {object} Response configuration object. You can call its `respond()` method to
+    *   configure what should the browser mock return when the response is
+    *   {@link angular.mock.service.$browser.xhr.flush flushed}.
+    */
   self.xhr.expectPOST   = angular.bind(self, self.xhr.expect, 'POST');
+
+  /**
+    * @ngdoc function
+    * @name angular.mock.service.$browser.xhr.expectDELETE
+    *
+    * @description
+    * Trains browser to expect a `DELETE` request and respond to it.
+    *
+    * @param {string} url Url path for which a request is expected.
+    * @returns {object} Response configuration object. You can call its `respond()` method to
+    *   configure what should the browser mock return when the response is
+    *   {@link angular.mock.service.$browser.xhr.flush flushed}.
+    */
   self.xhr.expectDELETE = angular.bind(self, self.xhr.expect, 'DELETE');
+
+  /**
+    * @ngdoc function
+    * @name angular.mock.service.$browser.xhr.expectPUT
+    *
+    * @description
+    * Trains browser to expect a `PUT` request and respond to it.
+    *
+    * @param {string} url Url path for which a request is expected.
+    * @returns {object} Response configuration object. You can call its `respond()` method to
+    *   configure what should the browser mock return when the response is
+    *   {@link angular.mock.service.$browser.xhr.flush flushed}.
+    */
   self.xhr.expectPUT    = angular.bind(self, self.xhr.expect, 'PUT');
+
+  /**
+    * @ngdoc function
+    * @name angular.mock.service.$browser.xhr.expectJSON
+    *
+    * @description
+    * Trains browser to expect a `JSON` request and respond to it.
+    *
+    * @param {string} url Url path for which a request is expected.
+    * @returns {object} Response configuration object. You can call its `respond()` method to
+    *   configure what should the browser mock return when the response is
+    *   {@link angular.mock.service.$browser.xhr.flush flushed}.
+    */
   self.xhr.expectJSON   = angular.bind(self, self.xhr.expect, 'JSON');
+
+  /**
+    * @ngdoc function
+    * @name angular.mock.service.$browser.xhr.flush
+    *
+    * @description
+    * Flushes all pending requests and executes xhr callbacks with the trained response as the
+    * argument.
+    */
   self.xhr.flush = function() {
     if (requests.length == 0) {
       throw new Error("No xhr requests to be flushed!");