Repository: angular/angular.js
File: src/auto/injector.js (JavaScript)

Code before:
 *
 * Here is an example of loading a bundle of modules, with a utility method called `getScript`:
 *
 * ```javascript
 * app.service('AmdLoader', function ($injector, $log) {
 *
 *  return function(name, config) {
 *    getScript(config).done(function () {
 *      $log.info('Script loaded : ' + name);
 *      onReady(name);
 *    });
 *
 *    function onReady(name) {
 *      var moduleName = name + '.html.bundle';
 *      $log.debug('AMD >> Loading Angular module [' + moduleName + '] ...');
 *
 *      if (config.modules) {
 *        $injector.loadNewModules(config.modules);
 *        $log.debug('AMD >> Children modules loaded >>>');
 *        $log.debug(config.modules);
 *      }
 *
 *      $injector.loadNewModules([moduleName]);
 *      $log.debug('AMD >> Angular module [' + moduleName + '] loaded.');
 *    }
 * });
 * ```
 *
 * @param {Module[]} mods A collection of modules to load.
 */


/**
 * @ngdoc service
 * @name $provide
 *
 * @description
 *
 * The {@link auto.$provide $provide} service has a number of methods for registering components
 * with the {@link auto.$injector $injector}. Many of these functions are also exposed on
 * {@link angular.Module}.
 *
 * An AngularJS **service** is a singleton object created by a **service factory**.  These **service
 * factories** are functions which, in turn, are created by a **service provider**.
 * The **service providers** are constructor functions. When instantiated they must contain a
 * property called `$get`, which holds the **service factory** function.
 *
 * When you request a service, the {@link auto.$injector $injector} is responsible for finding the
 * correct **service provider**, instantiating it and then calling its `$get` **service factory**
 * function to get the instance of the **service**.
 *

Review comment (suggestion):
FWIW, I find the example unnecessarily complicated. I would expect something like:

```js
app.factory('loadModule', function($injector) {
  return function loadModule(moduleName, bundleUrl) {
    return getScript(bundleUrl).then(function() { $injector.loadNewModules([moduleName]); });
  };
})
```

Code after:
 * * Previously compiled HTML will not be affected by newly loaded directives, filters and components.
 * * Modules cannot be unloaded.
 *
 * You can use {@link $injector#modules `$injector.modules`} to check whether a module has been loaded
 * into the injector, which may indicate whether the script has been executed already.
 *
 * ## Example
 *
 * Here is an example of loading a bundle of modules, with a utility method called `getScript`:
 *
 * ```javascript
 * app.factory('loadModule', function($injector) {
 *   return function loadModule(moduleName, bundleUrl) {
 *     return getScript(bundleUrl).then(function() { $injector.loadNewModules([moduleName]); });
 *   };
 * })
 * ```
 *
 * @param {Array<String|Function|Array>=} mods an array of modules to load into the application.
 *     Each item in the array should be the name of a predefined module or a (DI annotated)
 *     function that will be invoked by the injector as a `config` block.
 *     See: {@link angular.module modules}
 */


/**
 * @ngdoc service
 * @name $provide
 *
 * @description
 *
 * The {@link auto.$provide $provide} service has a number of methods for registering components
 * with the {@link auto.$injector $injector}. Many of these functions are also exposed on
 * {@link angular.Module}.
 *
 * An AngularJS **service** is a singleton object created by a **service factory**.  These **service
 * factories** are functions which, in turn, are created by a **service provider**.
 * The **service providers** are constructor functions. When instantiated they must contain a
 * property called `$get`, which holds the **service factory** function.
 *
 * When you request a service, the {@link auto.$injector $injector} is responsible for finding the
 * correct **service provider**, instantiating it and then calling its `$get` **service factory**
 * function to get the instance of the **service**.
 *
 * Often services have no configuration options and there is no need to add methods to the service
 * provider.  The provider will be no more than a constructor function with a `$get` property. For
 * these cases the {@link auto.$provide $provide} service has additional helper methods to register
 * services without specifying a provider.
 *
 * * {@link auto.$provide#provider provider(name, provider)} - registers a **service provider** with the
 *     {@link auto.$injector $injector}