doc(AUTO, NG_MOCK): Documenting the AUTO and NG_MOCK module

14 files changed, 486 insertions, 150 deletions

diff --git a/src/Browser.js b/src/Browser.js
index d4faebc8..84d9cd44 100644
--- a/src/Browser.js
+++ b/src/Browser.js
@@ -24,7 +24,7 @@ var XHR = window.XMLHttpRequest || function() {
  * - hide all the global state in the browser caused by the window object
  * - abstract away all the browser specific features and inconsistencies
  *
- * For tests we provide {@link angular.mock.service.$browser mock implementation} of the `$browser`
+ * For tests we provide {@link angular.module.NG_MOCK.$browser mock implementation} of the `$browser`
  * service, which can be used for convenient testing of the application without the interaction with
  * the real browser apis.
  */
diff --git a/src/Injector.js b/src/Injector.js
index 58b30fda..fbc6d3a0 100644
--- a/src/Injector.js
+++ b/src/Injector.js
@@ -9,37 +9,35 @@
  * Creates an injector function that can be used for retrieving services as well as for
  * dependency injection (see {@link guide/dev_guide.di dependency injection}).
  *
- * Creating an injector doesn't automatically create all of the `$eager`
- * {@link angular.service services}. You have to call `injector.eager()` to initialize them.
- *
- * @param {Object.<string, function()>=} [factories=angular.service] Map of the service factory
- *     functions.
- * @returns {function()} Injector function:
- *
- *   * `injector(serviceName)`:
- *     * `serviceName` - `{string=}` - Name of the service to retrieve.
- *
- * The injector function also has these properties:
- *
- *   * An `invoke` property which can be used to invoke methods with dependency-injected arguments.
- *    `injector.invoke(self, fn, locals)`
- *     * `self` -  The "`this`" to be used when invoking the function.
- *     * `fn` - The function to be invoked. The function may have the `$inject` property that
- *        lists the set of arguments which should be auto-injected.
- *        (see {@link guide/dev_guide.di dependency injection}).
- *     * `locals(array)` - Optional array of arguments to pass to the function
- *        invocation after the injection arguments.
- *   * An `eager` property which is used to initialize the eager services.
- *     `injector.eager()`
+
+ * @param {<string, function()>} modules... A list of module functions or their aliases. See
+ *        {@link angular.module}. The `NG` module must be explicitly added.
+ * @returns {function()} Injector function. See {@link angular.module.AUTO.$injector $injector}.
+ *
+ * @example
+ * Typical usage
+ * <pre>
+ *   // create an injector
+ *   var $injector = angular.injector('NG');
+ *
+ *   // use the injector to kick of your application
+ *   // use the type inference to auto inject arguments, or use implicit injection
+ *   $injector(function($rootScope, $compile, $document){
+ *     $compile($document)($rootScope);
+ *     $rootScope.$digest();
+ *   });
+ * </pre>
  */
 
 
 /**
- * @returns the $inject property of function. If not found the
- * the $inject is computed by looking at the toString of function and
- * extracting all arguments which and assuming that they are the
- * injection names.
+ * @ngdoc overview
+ * @name angular.module.AUTO
+ * @description
+ *
+ * Implicit module which gets automatically added to each {@link angular.module.AUTO.$injector $injector}.
  */
+
 var FN_ARGS = /^function\s*[^\(]*\(([^\)]*)\)/m;
 var FN_ARG_SPLIT = /,/;
 var FN_ARG = /^\s*(.+?)\s*$/;
@@ -60,6 +58,207 @@ function inferInjectionArgs(fn) {
 }
 
 ///////////////////////////////////////
+
+/**
+ * @ngdoc function
+ * @name angular.module.AUTO.$injector
+ * @function
+ *
+ * @description
+ *
+ * `$injector` function is used to retrieve object instances. Object instances are defined by
+ * {@link angular.module.AUTO.$provide provider}.
+ *
+ * The following always holds true:
+ *
+ * <pre>
+ *   var $injector = angular.injector();
+ *   expect($injector('$injector')).toBe($injector);
+ *   expect($injector(function($injector){
+ *     return $injector;
+ *   }).toBe($injector);
+ * </pre>
+ *
+ * # Injection Function Annotation
+ *
+ * JavaScript does not have annotations, and annotations are needed for dependency injection. The
+ * following ways are all valid way of annotating function with injection arguments and are equivalent.
+ *
+ * <pre>
+ *   // inferred (only works if code not minified/obfuscated)
+ *   $inject.invoke(function(serviceA){});
+ *
+ *   // annotated
+ *   function explicit(serviceA) {};
+ *   explicit.$inject = ['serviceA'];
+ *   $inject.invoke(explicit);
+ *
+ *   // inline
+ *   $inject.invoke(['serviceA', function(serviceA){}]);
+ * </pre>
+ *
+ * ## Inference
+ *
+ * In JavaScript calling `toString()` on a function returns the function definition. The definition can then be
+ * parsed and the function arguments can be extracted. *NOTE:* This does not work with minfication, and obfuscation
+ * tools since these tools change the argument names.
+ *
+ * ## `$inject` Annotation
+ * By adding a `$inject` property onto a function the injection parameters can be specified.
+ *
+ * ## Inline
+ * As an array of injection names, where the last item in the array is the function to call.
+ *
+ * @param {string, function()} argument  If the `argument` is:
+ *
+ *    - `string`: Retrieve an instance of a named object. If object does not exist, use the provider to create
+ *                a new instance. Calling the method repeatedly with the same name will always return the same
+ *                instance.
+ *    - `function`: Invoke the function. This is a short hand for `$injector.`{@link #invoke invoke(null, argument)}.
+ * @return the object instance or the return value of the invoked function.
+ */
+
+/**
+ * @ngdoc method
+ * @name angular.module.AUTO.$injector#invoke
+ * @methodOf angular.module.AUTO.$injector
+ *
+ * @description
+ * Invoke the method and supply the method arguments from the `$injector`.
+ *
+ * @param {Object} self The `this` for the invoked method.
+ * @param {function} fn The function to invoke. The function arguments come form the function annotation.
+ * @param {Object=} locals Optional object. If preset then any argument names are read from this object first, before
+ *   the `$injector` is consulted.
+ * @return the value returned by the invoked `fn` function.
+ */
+
+/**
+ * @ngdoc method
+ * @name angular.module.AUTO.$injector#instantiate
+ * @methodOf angular.module.AUTO.$injector
+ * @description
+ * Create a new instance of JS type. The method takes a constructor function invokes the new operator and supplies
+ * all of the arguments to the constructor function as specified by the constructor annotation.
+ *
+ * @param {function} Type Annotated constructor function.
+ * @param {Object=} locals Optional object. If preset then any argument names are read from this object first, before
+ *   the `$injector` is consulted.
+ * @return new instance of `Type`.
+ */
+
+/**
+ * @ngdoc method
+ * @name angular.module.AUTO.$injector#loadModule
+ * @methodOf angular.module.AUTO.$injector
+ * @description
+ * Load additional modules into the current injector configuration
+ *
+ * @param {Array} modules An array of modules, where module is a:
+ *
+ *   - `string`: look up the module function from {@link angular.module} and then treat as `function`.
+ *   - `function`: execute the module configuration function using
+ *      {@link angular.module.AUTO.$injector#invoke $injector.invoke()}
+ */
+
+
+
+/**
+ * @ngdoc object
+ * @name angular.module.AUTO.$provide
+ *
+ * @description
+ *
+ * Use `$provide` to register new providers with the `$injector`. The providers are the factories for the instance.
+ * The providers share the same name as the instance they create with the `Provide` suffixed to them.
+ *
+ * A provider is an object with a `$get()` method. The injector calls the `$get` method to create a new instance of
+ * a service. The Provider can have additional methods which would allow for configuration of the provider.
+ *
+ * <pre>
+ *   function GreetProvider() {
+ *     var salutation = 'Hello';
+ *
+ *     this.salutation = function(text) {
+ *       salutation = text;
+ *     };
+ *
+ *     this.$get = function() {
+ *       return function (name) {
+ *         return salutation + ' ' + name + '!';
+ *       };
+ *     };
+ *   }
+ *
+ *   describe('Greeter', function(){
+ *
+ *     beforeEach(inject(function($provide) {
+ *       $provide.service('greet', GreetProvider);
+ *     });
+ *
+ *     it('should greet', inject(function(greet) {
+ *       expect(greet('angular')).toEqual('Hello angular!');
+ *     }));
+ *
+ *     it('should allow configuration of salutation', inject(
+ *       function(greetProvider) {
+ *         greetProvider.salutation('Ahoj');
+ *       },
+ *       function(greet) {
+ *         expect(greet('angular')).toEqual('Ahoj angular!');
+ *       }
+ *     )};
+ *
+ *   });
+ * </pre>
+ */
+
+/**
+ * @ngdoc method
+ * @name angular.module.AUTO.$provide#service
+ * @methodOf angular.module.AUTO.$provide
+ * @description
+ *
+ * Register a provider for a service. The providers can be retrieved and can have additional configuration methods.
+ *
+ * @param {string} name The name of the instance. NOTE: the provider will be available under `name + 'Provide'` key.
+ * @param {(Object|function())} provider If the provider is:
+ * 
+ *   - `Object`: then it should have a `$get` method. The `$get` method will be invoked using
+ *               {@link angular.module.AUTO.$injector#invoke $injector.invoke()} when an instance needs to be created.
+ *   - `Constructor`: a new instance of the provider will be created using
+ *               {@link angular.module.AUTO.$injector#instantiate $injector.instantiate()}, then treated as `object`.
+ *
+ */
+
+/**
+ * @ngdoc method
+ * @name angular.module.AUTO.$provide#factory
+ * @methodOf angular.module.AUTO.$provide
+ * @description
+ *
+ * A short hand for configuring services if only `$get` method is required.
+ *
+ * @param {string} name The name of the instance. NOTE: the provider will be available under `name + 'Provide'` key.
+ * @param {function()} $getFn The $getFn for the instance creation. Internally this is a short hand for
+ * `$provide.service(name, {$get:$getFn})`.
+ */
+
+
+/**
+ * @ngdoc method
+ * @name angular.module.AUTO.$provide#value
+ * @methodOf angular.module.AUTO.$provide
+ * @description
+ *
+ * A short hand for configuring services if the `$get` method is a constant.
+ *
+ * @param {string} name The name of the instance. NOTE: the provider will be available under `name + 'Provide'` key.
+ * @param {function()} value The $getFn for the instance creation. Internally this is a short hand for
+ * `$provide.service(name, {$get:function(){ return value; }})`.
+ */
+
+
 function createInjector(modulesToLoad, moduleRegistry) {
   var cache = {},
       $injector = internalInjector(cache),
diff --git a/src/angular-mocks.js b/src/angular-mocks.js
index 1757b941..1bdf0b86 100644
--- a/src/angular-mocks.js
+++ b/src/angular-mocks.js
@@ -6,69 +6,49 @@
  */
 
 
-/*
- IN THE FINAL BUILD THIS FILE DOESN'T HAVE DIRECT ACCESS TO GLOBAL FUNCTIONS
- DEFINED IN Angular.js YOU *MUST* REFER TO THEM VIA angular OBJECT
- (e.g. angular.forEach(...)) AND MAKE SURE THAT THE GIVEN FUNCTION IS EXPORTED
- TO THE angular NAMESPACE in AngularPublic.js
-
- */
-
+window.angular = window.angular || {};
+angular.module = angular.module || {};
 
 /**
  * @ngdoc overview
- * @name angular.mock
+ * @name angular.module.NG_MOCK
  * @description
  *
- * The `angular.mock` object is a namespace for all built-in mock services that ship with angular.
- * It automatically replaces real services if the `angular-mocks.js` file is loaded after
- * `angular.js` and before any tests.
- *
- * 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.$log $log } - A mock implementation of the angular service log.
+ * The `NG_MOCK` is an angular module which is used with `NG` module and adds unit-test configuration as well as useful
+ * mocks to the {@link angular.module.AUTO.$injector $injector}.
  */
-window.angular = window.angular || {};
-angular.module = angular.module || {};
-angular.mock = angular.mock || {};
-
-angular.module.NG_MOCK = ['$provide', function($provide){
-  $provide.service('$browser', angular.mock.$BrowserProvider);
-  $provide.service('$exceptionHandler', angular.mock.$ExceptionHandlerProvider);
-  $provide.service('$log', angular.mock.$LogProvider);
-}];
+angular.module.NG_MOCK = function($provide){
+  $provide.service('$browser', angular.module.NG_MOCK.$BrowserProvider);
+  $provide.service('$exceptionHandler', angular.module.NG_MOCK.$ExceptionHandlerProvider);
+  $provide.service('$log', angular.module.NG_MOCK.$LogProvider);
+};
+angular.module.NG_MOCK.$inject = ['$provide'];
 
 /**
- * @ngdoc service
- * @name angular.mock.service.$browser
+ * @ngdoc object
+ * @name angular.module.NG_MOCK.$browser
  *
  * @description
- * This service is a mock implementation of {@link angular.service.$browser}. It provides fake
+ * This service is a mock implementation of {@link angular.module.NG.$browser}. It provides fake
  * implementation for commonly used browser apis that are hard to test, e.g. setTimeout, xhr,
- * cookies.
+ * cookies, etc...
  *
- * 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
+ * The api of this service is the same as that of the real {@link angular.module.NG.$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.
+ * - {@link #xhr} — enables testing of code that uses
+ *   the {@link angular.module.NG.$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.
+ *   {@link angular.module.NG.$defer $defer} for executing functions via the `setTimeout` api.
  */
-angular.mock.$BrowserProvider = function(){
+angular.module.NG_MOCK.$BrowserProvider = function(){
   this.$get = function(){
-    return new angular.mock.$Browser();
+    return new angular.module.NG_MOCK.$Browser();
   };
 };
-angular.mock.$Browser = function() {
+angular.module.NG_MOCK.$Browser = function() {
   var self = this,
       expectations = {},
       requests = [];
@@ -96,22 +76,23 @@ angular.mock.$Browser = function() {
 
 
   /**
-    * @ngdoc function
-    * @name angular.mock.service.$browser.xhr
+    * @ngdoc method
+    * @name angular.module.NG_MOCK.$browser#xhr
+    * @methodOf angular.module.NG_MOCK.$browser
     *
     * @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}
+    * - {@link #xhr.expectGET}
+    * - {@link #xhr.expectPOST}
+    * - {@link #xhr.expectPUT}
+    * - {@link #xhr.expectDELETE}
+    * - {@link #xhr.expectJSON}
     *
     * To flush pending requests in tests use
-    * {@link angular.mock.service.$browser.xhr.flush $browser.xhr.flush}.
+    * {@link #xhr.flush}.
     *
     * @param {string} method Expected HTTP method.
     * @param {string} url Url path for which a request is expected.
@@ -120,7 +101,7 @@ angular.mock.$Browser = function() {
     * @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}.
+    *   {@link #xhr.flush flushed}.
     */
   self.xhr = function(method, url, data, callback, headers) {
     headers = headers || {};
@@ -158,8 +139,9 @@ angular.mock.$Browser = function() {
   };
 
   /**
-    * @ngdoc function
-    * @name angular.mock.service.$browser.xhr.expectGET
+    * @ngdoc method
+    * @name angular.module.NG_MOCK.$browser#xhr.expectGET
+    * @methodOf angular.module.NG_MOCK.$browser
     *
     * @description
     * Trains browser to expect a `GET` request and respond to it.
@@ -167,13 +149,14 @@ angular.mock.$Browser = function() {
     * @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}.
+    *   {@link angular.module.NG_MOCK.$browser.xhr.flush flushed}.
     */
   self.xhr.expectGET    = angular.bind(self, self.xhr.expect, 'GET');
 
   /**
-    * @ngdoc function
-    * @name angular.mock.service.$browser.xhr.expectPOST
+   * @ngdoc method
+   * @name angular.module.NG_MOCK.$browser#xhr.expectPOST
+   * @methodOf angular.module.NG_MOCK.$browser
     *
     * @description
     * Trains browser to expect a `POST` request and respond to it.
@@ -181,13 +164,14 @@ angular.mock.$Browser = function() {
     * @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}.
+    *   {@link angular.module.NG_MOCK.$browser.xhr.flush flushed}.
     */
   self.xhr.expectPOST   = angular.bind(self, self.xhr.expect, 'POST');
 
   /**
-    * @ngdoc function
-    * @name angular.mock.service.$browser.xhr.expectDELETE
+   * @ngdoc method
+   * @name angular.module.NG_MOCK.$browser#xhr.expectDELETE
+   * @methodOf angular.module.NG_MOCK.$browser
     *
     * @description
     * Trains browser to expect a `DELETE` request and respond to it.
@@ -195,13 +179,14 @@ angular.mock.$Browser = function() {
     * @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}.
+    *   {@link angular.module.NG_MOCK.$browser.xhr.flush flushed}.
     */
   self.xhr.expectDELETE = angular.bind(self, self.xhr.expect, 'DELETE');
 
   /**
-    * @ngdoc function
-    * @name angular.mock.service.$browser.xhr.expectPUT
+   * @ngdoc method
+   * @name angular.module.NG_MOCK.$browser#xhr.expectPUT
+   * @methodOf angular.module.NG_MOCK.$browser
     *
     * @description
     * Trains browser to expect a `PUT` request and respond to it.
@@ -209,13 +194,14 @@ angular.mock.$Browser = function() {
     * @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}.
+    *   {@link angular.module.NG_MOCK.$browser.xhr.flush flushed}.
     */
   self.xhr.expectPUT    = angular.bind(self, self.xhr.expect, 'PUT');
 
   /**
-    * @ngdoc function
-    * @name angular.mock.service.$browser.xhr.expectJSON
+   * @ngdoc method
+   * @name angular.module.NG_MOCK.$browser#xhr.expectJSON
+   * @methodOf angular.module.NG_MOCK.$browser
     *
     * @description
     * Trains browser to expect a `JSON` request and respond to it.
@@ -223,13 +209,14 @@ angular.mock.$Browser = function() {
     * @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}.
+    *   {@link angular.module.NG_MOCK.$browser.xhr.flush flushed}.
     */
   self.xhr.expectJSON   = angular.bind(self, self.xhr.expect, 'JSON');
 
   /**
-    * @ngdoc function
-    * @name angular.mock.service.$browser.xhr.flush
+   * @ngdoc method
+   * @name angular.module.NG_MOCK.$browser#xhr.flush
+   * @methodOf angular.module.NG_MOCK.$browser
     *
     * @description
     * Flushes all pending requests and executes xhr callbacks with the trained response as the
@@ -277,6 +264,16 @@ angular.mock.$Browser = function() {
   };
 
 
+  /**
+   * @ngdoc method
+   * @name angular.module.NG_MOCK.$browser#defer.flush
+   * @methodOf angular.module.NG_MOCK.$browser
+   *
+   * @description
+   * Flushes all pending requests and executes the defer callbacks.
+   *
+   * @param {number=} number of miliseconds to flush. See {@link #defer.now}
+   */
   self.defer.flush = function(delay) {
     if (angular.isDefined(delay)) {
       self.defer.now += delay;
@@ -290,17 +287,25 @@ angular.mock.$Browser = function() {
       self.deferredFns.shift().fn();
     }
   };
+  /**
+   * @ngdoc property
+   * @name angular.module.NG_MOCK.$browser#defer.now
+   * @propertyOf angular.module.NG_MOCK.$browser
+   *
+   * @description
+   * Current milliseconds mock time.
+   */
 
   self.$$baseHref = '';
   self.baseHref = function() {
     return this.$$baseHref;
   };
 }
-angular.mock.$Browser.prototype = {
+angular.module.NG_MOCK.$Browser.prototype = {
 
 /**
-  * @name angular.mock.service.$browser#poll
-  * @methodOf angular.mock.service.$browser
+  * @name angular.module.NG_MOCK.$browser#poll
+  * @methodOf angular.module.NG_MOCK.$browser
   *
   * @description
   * run all fns in pollFns
@@ -351,19 +356,45 @@ angular.mock.$Browser.prototype = {
 
 
 /**
- * @ngdoc service
- * @name angular.mock.service.$exceptionHandler
+ * @ngdoc object
+ * @name angular.module.NG_MOCK.$exceptionHandlerProvider
  *
  * @description
- * Mock implementation of {@link angular.service.$exceptionHandler} that rethrows any error passed
- * into `$exceptionHandler`. If any errors are are passed into the handler in tests, it typically
- * means that there is a bug in the application or test, so this mock will make these tests fail.
+ * Configures the mock implementation of {@link angular.module.NG.$exceptionHandler} to rethrow or to log errors passed
+ * into the `$exceptionHandler`.
+ */
+
+/**
+ * @ngdoc object
+ * @name angular.module.NG_MOCK.$exceptionHandler
  *
- * See {@link angular.mock} for more info on angular mocks.
+ * @description
+ * Mock implementation of {@link angular.module.NG.$exceptionHandler} that rethrows or logs errors passed
+ * into it. See {@link angular.module.NG_MOCK.$exceptionHandlerProvider $exceptionHandlerProvider} for configuration
+ * information.
  */
-angular.mock.$ExceptionHandlerProvider = function(){
+
+angular.module.NG_MOCK.$ExceptionHandlerProvider = function(){
   var handler;
 
+  /**
+   * @ngdoc method
+   * @name angular.module.NG_MOCK.$exceptionHandlerProvider#mode
+   * @methodOf angular.module.NG_MOCK.$exceptionHandlerProvider
+   *
+   * @description
+   * Sets the logging mode.
+   *
+   * @param {string} mode Mode of operation, defaults to `rethrow`.
+   *
+   *   - `rethrow`: If any errors are are passed into the handler in tests, it typically
+   *                means that there is a bug in the application or test, so this mock will
+   *                make these tests fail.
+   *   - `log`: Sometimes it is desirable to test that an error is throw, for this case the `log` mode stores the
+   *            error and allows later assertion of it.
+   *            See {@link angular.module.NG_MOCK.$log#assertEmpty assertEmpty()} and
+   *             {@link angular.module.NG_MOCK.$log#reset reset()}
+   */
   this.mode = function(mode){
     switch(mode) {
       case 'rethrow':
@@ -393,16 +424,15 @@ angular.mock.$ExceptionHandlerProvider = function(){
 
 /**
  * @ngdoc service
- * @name angular.mock.service.$log
+ * @name angular.module.NG_MOCK.$log
  *
  * @description
- * Mock implementation of {@link angular.service.$log} that gathers all logged messages in arrays
+ * Mock implementation of {@link angular.module.NG.$log} that gathers all logged messages in arrays
  * (one array per logging level). These arrays are exposed as `logs` property of each of the
  * level-specific log function, e.g. for level `error` the array is exposed as `$log.error.logs`.
  *
- * See {@link angular.mock} for more info on angular mocks.
  */
-angular.mock.$LogProvider = function(){
+angular.module.NG_MOCK.$LogProvider = function(){
 
   function concat(array1, array2, index) {
     return array1.concat(Array.prototype.slice.call(array2, index));
@@ -417,14 +447,62 @@ angular.mock.$LogProvider = function(){
       error: function() { $log.error.logs.push(concat([], arguments, 0)); }
     };
 
+    /**
+     * @ngdoc method
+     * @name angular.module.NG_MOCK.$log#reset
+     * @methodOf angular.module.NG_MOCK.$log
+     *
+     * @description
+     * Reset all of the logging arrays to empty.
+     */
     $log.reset = function (){
+      /**
+       * @ngdoc property
+       * @name angular.module.NG_MOCK.$log#log.logs
+       * @propertyOf angular.module.NG_MOCK.$log
+       *
+       * @description
+       * Array of logged messages.
+       */
       $log.log.logs = [];
+      /**
+       * @ngdoc property
+       * @name angular.module.NG_MOCK.$log#warn.logs
+       * @propertyOf angular.module.NG_MOCK.$log
+       *
+       * @description
+       * Array of logged messages.
+       */
       $log.warn.logs = [];
+      /**
+       * @ngdoc property
+       * @name angular.module.NG_MOCK.$log#info.logs
+       * @propertyOf angular.module.NG_MOCK.$log
+       *
+       * @description
+       * Array of logged messages.
+       */
       $log.info.logs = [];
+      /**
+       * @ngdoc property
+       * @name angular.module.NG_MOCK.$log#error.logs
+       * @propertyOf angular.module.NG_MOCK.$log
+       *
+       * @description
+       * Array of logged messages.
+       */
       $log.error.logs = [];
     };
 
-    $log.assertEmpty = function(){
+    /**
+     * @ngdoc method
+     * @name angular.module.NG_MOCK.$log#assertEmpty
+     * @methodOf angular.module.NG_MOCK.$log
+     *
+     * @description
+     * Assert that the all of the logging methods have no logged messages. If messages present, an exception is thrown.
+     */
+    $log.assertEmpty = function() {
       var errors = [];
       angular.forEach(['error', 'warn', 'info', 'log'], function(logLevel) {
         angular.forEach($log[logLevel].logs, function(log) {
@@ -448,6 +526,12 @@ angular.mock.$LogProvider = function(){
 
 
 /**
+ * @ngdoc object
+ * @name angular.module.NG_MOCK.TzDate
+ * @description
+ *
+ * *NOTE*: this is not an injectable instance, just a globally available mock class of `Date`.
+ *
  * Mock of the Date type which has its timezone specified via constroctor arg.
  *
  * The main purpose is to create Date-like instances with timezone fixed to the specified timezone
@@ -477,7 +561,7 @@ angular.mock.$LogProvider = function(){
  * </pre>
  *
  */
-angular.mock.TzDate = function (offset, timestamp) {
+angular.module.NG_MOCK.TzDate = function (offset, timestamp) {
   var self = new Date(0);
   if (angular.isString(timestamp)) {
     var tsStr = timestamp;
@@ -580,15 +664,24 @@ angular.mock.TzDate = function (offset, timestamp) {
 }
 
 //make "tzDateInstance instanceof Date" return true
-angular.mock.TzDate.prototype = Date.prototype;
+angular.module.NG_MOCK.TzDate.prototype = Date.prototype;
 
 
 /**
- * Method for serializing common objects into strings, useful for debugging.
+ * @ngdoc function
+ * @name angular.module.NG_MOCK.debug
+ * @description
+ *
+ * *NOTE*: this is not an injectable instance, just a globally available function.
+ *
+ * Method for serializing common angular objects (scope, elements, etc..) into strings, useful for debugging.
+ *
+ * This method is also available on window, where it can be used to display objects on debug console.
+ *
  * @param {*} object - any object to turn into string.
  * @return a serialized string of the argument
  */
-angular.mock.dump = function(object){
+angular.module.NG_MOCK.dump = function(object){
   var out;
   if (angular.isElement(object)) {
     object = angular.element(object);
@@ -633,13 +726,57 @@ window.jstestdriver && (function(window){
   window.dump = function() {
     var args = [];
     angular.forEach(arguments, function(arg){
-      args.push(angular.mock.dump(arg));
+      args.push(angular.module.NG_MOCK.dump(arg));
     });
     jstestdriver.console.log.apply(jstestdriver.console, args);
   };
 })(window);
 
 
+/**
+ * @ngdoc function
+ * @name angular.module.NG_MOCK.inject
+ * @description
+ *
+ * *NOTE*: this is not an injectable instance, just a globally available function on window.
+ *
+ * This function wraps a test method into an injectable method. It create one
+ * {@link angular.module.AUTO.$injector $injector} per test, which is then used for testing.
+ *
+ * Here is an example of what a typical jasmine tests looks like with the inject method.
+ * <pre>
+ *   describe('MyApp', function() {
+ *
+ *     // Argument inference is used to inject the $provide service
+ *     beforeEach(inject(function($provide, $rootScope) {
+ *       // $provide service is configured as needed
+ *       $provide.value('version', 'v1.0.1');
+ *       $rootScope.value = 123;
+ *     });
+ *
+ *     // Argument inference is used to inject the $rootScope as well as the version
+ *     it('should provide a version', inject(function($rootScope, version){
+ *       expect(version).toEqual('v1.0.1');
+ *       expect($rootScope.value).toEqual(123);
+ *     });
+ *
+ *     // The inject can also chain the methods
+ *     it('should override a version and test the new version is injected', inject(
+ *       function($provide) {
+ *         $provide.value('version', 'overridden'); // override version here
+ *       },
+ *       function(version) {
+ *         expect(version).toEqual('overridden');
+ *       }
+ *     ));
+ *
+ *   });
+ *
+ * </pre>
+ *
+ * @param {*} fns... any number of functions which will be injected using the injector.
+ * @return a method
+ */
 window.jasmine && (function(window){
   window.inject = function (){
     var blockFns = Array.prototype.slice.call(arguments, 0);
diff --git a/src/apis.js b/src/apis.js
index 08120c99..6f9b1d0a 100644
--- a/src/apis.js
+++ b/src/apis.js
@@ -10,7 +10,7 @@
  *         that is also assigned to the $$hashKey property of the object.
  *
  * @param obj
- * @returns {String} hash string such that the same input will have the same hash string.
+ * @returns {string} hash string such that the same input will have the same hash string.
  *         The resulting string key is in 'type:hashKey' format.
  */
 function hashKey(obj) {
diff --git a/src/scenario/Application.js b/src/scenario/Application.js
index e255041b..f4f4b974 100644
--- a/src/scenario/Application.js
+++ b/src/scenario/Application.js
@@ -44,8 +44,8 @@ angular.scenario.Application.prototype.getWindow_ = function() {
  *
  * @param {string} url The URL. If it begins with a # then only the
  *   hash of the page is changed.
- * @param {Function} loadFn function($window, $document) Called when frame loads.
- * @param {Function} errorFn function(error) Called if any error when loading.
+ * @param {function()} loadFn function($window, $document) Called when frame loads.
+ * @param {function()} errorFn function(error) Called if any error when loading.
  */
 angular.scenario.Application.prototype.navigateTo = function(url, loadFn, errorFn) {
   var self = this;
@@ -78,7 +78,7 @@ angular.scenario.Application.prototype.navigateTo = function(url, loadFn, errorF
  * Executes a function in the context of the tested application. Will wait
  * for all pending angular xhr requests before executing.
  *
- * @param {Function} action The callback to execute. function($window, $document)
+ * @param {function()} action The callback to execute. function($window, $document)
  *  $document is a jQuery wrapped document.
  */
 angular.scenario.Application.prototype.executeAction = function(action) {
diff --git a/src/scenario/Describe.js b/src/scenario/Describe.js
index 45a5aa63..4d52e9d5 100644
--- a/src/scenario/Describe.js
+++ b/src/scenario/Describe.js
@@ -45,7 +45,7 @@ angular.scenario.Describe.specId = 0;
 /**
  * Defines a block to execute before each it or nested describe.
  *
- * @param {Function} body Body of the block.
+ * @param {function()} body Body of the block.
  */
 angular.scenario.Describe.prototype.beforeEach = function(body) {
   this.beforeEachFns.push(body);
@@ -54,7 +54,7 @@ angular.scenario.Describe.prototype.beforeEach = function(body) {
 /**
  * Defines a block to execute after each it or nested describe.
  *
- * @param {Function} body Body of the block.
+ * @param {function()} body Body of the block.
  */
 angular.scenario.Describe.prototype.afterEach = function(body) {
   this.afterEachFns.push(body);
@@ -64,7 +64,7 @@ angular.scenario.Describe.prototype.afterEach = function(body) {
  * Creates a new describe block that's a child of this one.
  *
  * @param {string} name Name of the block. Appended to the parent block's name.
- * @param {Function} body Body of the block.
+ * @param {function()} body Body of the block.
  */
 angular.scenario.Describe.prototype.describe = function(name, body) {
   var child = new angular.scenario.Describe(name, this);
@@ -76,7 +76,7 @@ angular.scenario.Describe.prototype.describe = function(name, body) {
  * Same as describe() but makes ddescribe blocks the only to run.
  *
  * @param {string} name Name of the test.
- * @param {Function} body Body of the block.
+ * @param {function()} body Body of the block.
  */
 angular.scenario.Describe.prototype.ddescribe = function(name, body) {
   var child = new angular.scenario.Describe(name, this);
@@ -94,7 +94,7 @@ angular.scenario.Describe.prototype.xdescribe = angular.noop;
  * Defines a test.
  *
  * @param {string} name Name of the test.
- * @param {Function} vody Body of the block.
+ * @param {function()} vody Body of the block.
  */
 angular.scenario.Describe.prototype.it = function(name, body) {
   this.its.push({
@@ -112,7 +112,7 @@ angular.scenario.Describe.prototype.it = function(name, body) {
  * Same as it() but makes iit tests the only test to run.
  *
  * @param {string} name Name of the test.
- * @param {Function} body Body of the block.
+ * @param {function()} body Body of the block.
  */
 angular.scenario.Describe.prototype.iit = function(name, body) {
   this.it.apply(this, arguments);
diff --git a/src/scenario/Future.js b/src/scenario/Future.js
index 598731fa..335dd2bb 100644
--- a/src/scenario/Future.js
+++ b/src/scenario/Future.js
@@ -4,8 +4,8 @@
  * A future action in a spec.
  *
  * @param {string} name of the future action
- * @param {Function} future callback(error, result)
- * @param {Function} Optional. function that returns the file/line number.
+ * @param {function()} future callback(error, result)
+ * @param {function()} Optional. function that returns the file/line number.
  */
 angular.scenario.Future = function(name, behavior, line) {
   this.name = name;
@@ -19,7 +19,7 @@ angular.scenario.Future = function(name, behavior, line) {
 /**
  * Executes the behavior of the closure.
  *
- * @param {Function} doneFn Callback function(error, result)
+ * @param {function()} doneFn Callback function(error, result)
  */
 angular.scenario.Future.prototype.execute = function(doneFn) {
   var self = this;
@@ -40,7 +40,7 @@ angular.scenario.Future.prototype.execute = function(doneFn) {
 /**
  * Configures the future to convert it's final with a function fn(value)
  *
- * @param {Function} fn function(value) that returns the parsed value
+ * @param {function()} fn function(value) that returns the parsed value
  */
 angular.scenario.Future.prototype.parsedWith = function(fn) {
   this.parser = fn;
diff --git a/src/scenario/ObjectModel.js b/src/scenario/ObjectModel.js
index 76e0201a..b4dad1a5 100644
--- a/src/scenario/ObjectModel.js
+++ b/src/scenario/ObjectModel.js
@@ -121,7 +121,7 @@ angular.scenario.ObjectModel = function(runner) {
  * Adds a listener for an event.
  *
  * @param {string} eventName Name of the event to add a handler for
- * @param {Function} listener Function that will be called when event is fired
+ * @param {function()} listener Function that will be called when event is fired
  */
 angular.scenario.ObjectModel.prototype.on = function(eventName, listener) {
   eventName = eventName.toLowerCase();
diff --git a/src/scenario/Runner.js b/src/scenario/Runner.js
index fba076a8..d71236bd 100644
--- a/src/scenario/Runner.js
+++ b/src/scenario/Runner.js
@@ -61,7 +61,7 @@ angular.scenario.Runner.prototype.on = function(eventName, listener) {
  * @see Describe.js
  *
  * @param {string} name Name of the block
- * @param {Function} body Body of the block
+ * @param {function()} body Body of the block
  */
 angular.scenario.Runner.prototype.describe = function(name, body) {
   var self = this;
@@ -82,7 +82,7 @@ angular.scenario.Runner.prototype.describe = function(name, body) {
  * @see Describe.js
  *
  * @param {string} name Name of the block
- * @param {Function} body Body of the block
+ * @param {function()} body Body of the block
  */
 angular.scenario.Runner.prototype.ddescribe = function(name, body) {
   var self = this;
@@ -103,7 +103,7 @@ angular.scenario.Runner.prototype.ddescribe = function(name, body) {
  * @see Describe.js
  *
  * @param {string} name Name of the block
- * @param {Function} body Body of the block
+ * @param {function()} body Body of the block
  */
 angular.scenario.Runner.prototype.it = function(name, body) {
   this.currentDescribe.it(name, body);
@@ -115,7 +115,7 @@ angular.scenario.Runner.prototype.it = function(name, body) {
  * @see Describe.js
  *
  * @param {string} name Name of the block
- * @param {Function} body Body of the block
+ * @param {function()} body Body of the block
  */
 angular.scenario.Runner.prototype.iit = function(name, body) {
   this.currentDescribe.iit(name, body);
@@ -127,7 +127,7 @@ angular.scenario.Runner.prototype.iit = function(name, body) {
  *
  * @see Describe.js
  *
- * @param {Function} Callback to execute
+ * @param {function()} Callback to execute
  */
 angular.scenario.Runner.prototype.beforeEach = function(body) {
   this.currentDescribe.beforeEach(body);
@@ -139,7 +139,7 @@ angular.scenario.Runner.prototype.beforeEach = function(body) {
  *
  * @see Describe.js
  *
- * @param {Function} Callback to execute
+ * @param {function()} Callback to execute
  */
 angular.scenario.Runner.prototype.afterEach = function(body) {
   this.currentDescribe.afterEach(body);
diff --git a/src/scenario/Scenario.js b/src/scenario/Scenario.js
index 0df74dae..a7979342 100644
--- a/src/scenario/Scenario.js
+++ b/src/scenario/Scenario.js
@@ -13,7 +13,7 @@ angular.scenario = angular.scenario || {};
  * Defines a new output format.
  *
  * @param {string} name the name of the new output format
- * @param {Function} fn function(context, runner) that generates the output
+ * @param {function()} fn function(context, runner) that generates the output
  */
 angular.scenario.output = angular.scenario.output || function(name, fn) {
   angular.scenario.output[name] = fn;
@@ -29,7 +29,7 @@ angular.scenario.output = angular.scenario.output || function(name, fn) {
  *   functions.
  *
  * @param {string} name The name of the statement
- * @param {Function} fn Factory function(), return a function for
+ * @param {function()} fn Factory function(), return a function for
  *  the statement.
  */
 angular.scenario.dsl = angular.scenario.dsl || function(name, fn) {
@@ -65,7 +65,7 @@ angular.scenario.dsl = angular.scenario.dsl || function(name, fn) {
  * created for you.
  *
  * @param {string} name The name of the matcher
- * @param {Function} fn The matching function(expected).
+ * @param {function()} fn The matching function(expected).
  */
 angular.scenario.matcher = angular.scenario.matcher || function(name, fn) {
   angular.scenario.matcher[name] = function(expected) {
@@ -148,8 +148,8 @@ angular.scenario.setUpAndRun = function(config) {
  * continueFunction to continute iterating.
  *
  * @param {Array} list list to iterate over
- * @param {Function} iterator Callback function(value, continueFunction)
- * @param {Function} done Callback function(error, result) called when
+ * @param {function()} iterator Callback function(value, continueFunction)
+ * @param {function()} done Callback function(error, result) called when
  *   iteration finishes or an error occurs.
  */
 function asyncForEach(list, iterator, done) {
diff --git a/src/scenario/SpecRunner.js b/src/scenario/SpecRunner.js
index 0d6274a4..eacf13a8 100644
--- a/src/scenario/SpecRunner.js
+++ b/src/scenario/SpecRunner.js
@@ -18,7 +18,7 @@ angular.scenario.SpecRunner = function() {
  * based on the describe nesting.
  *
  * @param {Object} spec A spec object
- * @param {Function} specDone function that is called when the spec finshes. Function(error, index)
+ * @param {function()} specDone function that is called when the spec finshes. Function(error, index)
  */
 angular.scenario.SpecRunner.prototype.run = function(spec, specDone) {
   var self = this;
@@ -85,8 +85,8 @@ angular.scenario.SpecRunner.prototype.run = function(spec, specDone) {
  * Note: Do not pass line manually. It happens automatically.
  *
  * @param {string} name Name of the future
- * @param {Function} behavior Behavior of the future
- * @param {Function} line fn() that returns file/line number
+ * @param {function()} behavior Behavior of the future
+ * @param {function()} line fn() that returns file/line number
  */
 angular.scenario.SpecRunner.prototype.addFuture = function(name, behavior, line) {
   var future = new angular.scenario.Future(name, angular.bind(this, behavior), line);
@@ -100,8 +100,8 @@ angular.scenario.SpecRunner.prototype.addFuture = function(name, behavior, line)
  * Note: Do not pass line manually. It happens automatically.
  *
  * @param {string} name Name of the future
- * @param {Function} behavior Behavior of the future
- * @param {Function} line fn() that returns file/line number
+ * @param {function()} behavior Behavior of the future
+ * @param {function()} line fn() that returns file/line number
  */
 angular.scenario.SpecRunner.prototype.addFutureAction = function(name, behavior, line) {
   var self = this;
diff --git a/src/scenario/output/Html.js b/src/scenario/output/Html.js
index 1c2216b5..326928d8 100644
--- a/src/scenario/output/Html.js
+++ b/src/scenario/output/Html.js
@@ -160,7 +160,7 @@ angular.scenario.output('html', function(context, runner, model) {
    * Add an error to a step.
    *
    * @param {Object} The JQuery wrapped context
-   * @param {Function} fn() that should return the file/line number of the error
+   * @param {function()} fn() that should return the file/line number of the error
    * @param {Object} the error.
    */
   function addError(context, line, error) {
diff --git a/src/service/exceptionHandler.js b/src/service/exceptionHandler.js
index b0c8e822..c53118b4 100644
--- a/src/service/exceptionHandler.js
+++ b/src/service/exceptionHandler.js
@@ -11,7 +11,7 @@
  * the browser console.
  *
  * In unit tests, if `angular-mocks.js` is loaded, this service is overriden by
- * {@link angular.mock.service.$exceptionHandler mock $exceptionHandler}
+ * {@link angular.module.NG_MOCK.$exceptionHandler mock $exceptionHandler}
  *
  * @example
  */
diff --git a/src/service/formFactory.js b/src/service/formFactory.js
index 8ba8ce79..5230d45b 100644
--- a/src/service/formFactory.js
+++ b/src/service/formFactory.js
@@ -180,7 +180,7 @@ function $FormFactoryProvider() {
    * Upon receiving the `$valid` event from the widget update the `$error`, `$valid` and `$invalid`
    * properties of both the widget as well as the from.
    *
-   * @param {String} validationKey The validation key to be used when updating the `$error` object.
+   * @param {string} validationKey The validation key to be used when updating the `$error` object.
    *    The validation key is what will allow the template to bind to a specific validation error
    *    such as `<div ng:show="form.$error.KEY">error for key</div>`.
    */
@@ -194,7 +194,7 @@ function $FormFactoryProvider() {
    * Upon receiving the `$invalid` event from the widget update the `$error`, `$valid` and `$invalid`
    * properties of both the widget as well as the from.
    *
-   * @param {String} validationKey The validation key to be used when updating the `$error` object.
+   * @param {string} validationKey The validation key to be used when updating the `$error` object.
    *    The validation key is what will allow the template to bind to a specific validation error
    *    such as `<div ng:show="form.$error.KEY">error for key</div>`.
    */