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

1 files changed, 225 insertions, 26 deletions

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),