docs(di): Edits to DI.

Closes angular#1420

Author: naomiblack

modules/angular2/di.js

@@ -2,7 +2,7 @@
  * @module
  * @public
  * @description
- * This is a description
+ * The `di` module provides dependency injection container services.
  */
 
 export {Inject, InjectPromise, InjectLazy, Injectable, Optional, DependencyAnnotation} from './src/di/annotations';

modules/angular2/di_annotations.js

@@ -2,6 +2,6 @@
  * @module
  * @public
  * @description
- * This is a description
+ * Annotations which controll how the dependencies are resolved by the [Injector].
  */
 

modules/angular2/di_errors.js

@@ -2,6 +2,6 @@
  * @module
  * @public
  * @description
- * This is a description
+ * Errors thrown by the [Injector].
  */
 

modules/angular2/directives.js

@@ -2,7 +2,7 @@
  * @module
  * @public
  * @description
- * Describe the directives module here
+ * Common directives shipped with Angualr.
  */
 
 export * from './src/directives/class';

modules/angular2/src/core/compiler/compiler.js

@@ -41,7 +41,7 @@ export class CompilerCache {
 }
 
 /**
- * @exportedAs angular2/template
+ * @exportedAs angular2/view
  */
 @Injectable()
 export class Compiler {

modules/angular2/src/core/compiler/view_container.js

@@ -11,7 +11,7 @@ import * as vhModule from './view_hydrator';
 import {Renderer} from 'angular2/src/render/api';
 
 /**
- * @exportedAs angular2/template
+ * @exportedAs angular2/view
  */
 export class ViewContainer {
  viewFactory: vfModule.ViewFactory;

modules/angular2/src/di/annotations.js

@@ -1,7 +1,7 @@
 import {CONST} from "angular2/src/facade/lang";
 
 /**
- * A parameter annotation that creates a synchronous eager dependency.
+ * A parameter annotation that specifies a dependency.
  *
  * ```
  * class AComponent {
@@ -20,7 +20,7 @@ export class Inject {
 }
 
 /**
- * A parameter annotation that creates an asynchronous eager dependency.
+ * A parameter annotation that specifies a [Promise] of a dependency.
  *
  * ```
  * class AComponent {
@@ -62,7 +62,9 @@ export class InjectLazy {
 }
 
 /**
- * A parameter annotation that marks a dependency as optional. (Injects `null` if not found.)
+ * A parameter annotation that marks a dependency as optional. [Injector] provides `null` if the dependency is not 
+ * found.
+ * 
  * ```
  * class AComponent {
  * constructor(@Optional() aService:MyService) {
@@ -82,8 +84,7 @@ export class Optional {
 /**
  * `DependencyAnnotation` is used by the framework to extend DI.
  *
- * Only annotations implementing `DependencyAnnotation` will be added
- * to the list of dependency properties.
+ * Only annotations implementing `DependencyAnnotation` are added to the list of dependency properties.
  *
  * For example:
  *
@@ -118,8 +119,8 @@ export class DependencyAnnotation {
 }
 
 /**
- * A marker annotation that marks a class as available to `Injector`s for creation. Used by tooling for generating 
- * constructor stubs. 
+ * A marker annotation that marks a class as available to `Injector` for creation. Used by tooling for
+ * generating constructor stubs.
  *
  * ```
  * class NeedsService {

modules/angular2/src/di/binding.js

@@ -50,16 +50,16 @@ var _EMPTY_LIST = []; // TODO: make const when supported
 export class Binding {
 
  /**
- * Token used when retriving this binding. Usually the [Type].
+ * Token used when retrieving this binding. Usually the [Type].
  */
  token;
 
  /**
- * Bind an interface to an implementation / subclass.
+ * Binds an interface to an implementation / subclass.
  *
  * ## Example
  *
- * Becuse `toAlias` and `toClass` are often confused the example contains both use cases for easy comparison.
+ * Becuse `toAlias` and `toClass` are often confused, the example contains both use cases for easy comparison.
  *
  * ```javascript
  *
@@ -86,7 +86,7 @@ export class Binding {
  toClass:Type;
 
  /**
- * Bind a key to a value.
+ * Binds a key to a value.
  *
  * ## Example
  *
@@ -101,10 +101,10 @@ export class Binding {
  toValue;
 
  /**
- * Bind a key to an alias of an existing key.
+ * Binds a key to the alias for an existing key.
  *
- * An alias means that we will return the same instance as if the alias token was used. (This is in contrast to
- * `toClass` where a separet instance of `toClass` will be returned.)
+ * An alias means that [Injector] returns the same instance as if the alias token was used. This is in contrast to
+ * `toClass` where a separate instance of `toClass` is returned.
  *
  * ## Example
  *
@@ -127,15 +127,15 @@ export class Binding {
  *
  * expect(injectorAlias.get(Vehicle)).toBe(injectorAlias.get(Car));
  * expect(injectorAlias.get(Vehicle) instanceof Car).toBe(true);
-
+ *
  * expect(injectorClass.get(Vehicle)).not.toBe(injectorClass.get(Car));
  * expect(injectorClass.get(Vehicle) instanceof Car).toBe(true);
  * ```
  */
  toAlias;
 
  /**
- * Bind a key to a function which computes the value.
+ * Binds a key to a function which computes the value.
  *
  * ## Example
  *
@@ -153,7 +153,7 @@ export class Binding {
  toFactory:Function;
 
  /**
- * Bind a key to a function which computes the value asynchronously.
+ * Binds a key to a function which computes the value asynchronously.
  *
  * ## Example
  *
@@ -170,15 +170,17 @@ export class Binding {
  * injector.asyncGet(String).then((v) => expect(v).toBe('Value: 3'));
  * ```
  *
- * The interesting thing to note is that event thougt `Numeber` has an async factory, the `String` factory
- * function takes the resolved value. This shows that the [Injector] delays executing of the `String` factory
- * until after the `Number` is resolved. This can only be done if the `token` is retrive
+ * The interesting thing to note is that event though `Number` has an async factory, the `String` factory
+ * function takes the resolved value. This shows that the [Injector] delays executing the `String` factory
+ * until after the `Number` is resolved. This can only be done if the `token` is retrieved using the 
+ * [Injector.asyncGet] API.
+ *
  */
  toAsyncFactory:Function;
 
  /**
- * Used in conjunction with `toFactory` or `toAsyncFactory` and specifies the `token`s which should be injected
- * into the factory function.
+ * Used in conjunction with `toFactory` or `toAsyncFactory` and specifies a set of dependencies (as `token`s) which
+ * should be injected into the factory function.
  *
  * ## Example
  *
@@ -216,7 +218,9 @@ export class Binding {
  }
 
  /**
- * 
+ * Converts the [Binding] into [ResolvedBinding].
+ *
+ * [Injector] internaly only uses [ResolvedBindings], [Binding] contains convenience sugar.
  */
  resolve(): ResolvedBinding {
  var factoryFn:Function;
@@ -250,29 +254,31 @@ export class Binding {
 }
 
 /**
- * An internal resolved representaion of a [Binding] used by [Injector].
- * 
- * A [Binding] is resolved when it has a factory fonction. Binding to a class, alias, or value, are just convenience
- * methods, as [Injector] only operates on calling factory functions. 
+ * An internal resolved representation of a [Binding] used by the [Injector].
+ *
+ * A [Binding] is resolved when it has a factory function. Binding to a class, alias, or value, are just convenience
+ * methods, as [Injector] only operates on calling factory functions.
+ *
+ * @exportedAs angular2/di
  */
 export class ResolvedBinding {
  /**
  * A key, usually a [Type].
  */
  key:Key;
- 
+
  /**
- * Factory function which can return an instance of [key].
+ * Factory function which can return an instance of represented by a [key].
  */
  factory:Function;
- 
+
  /**
  * Arguments (dependencies) to the [factory] function.
  */
  dependencies:List<Dependency>;
- 
+
  /**
- * Specifies if the [factory] function returns an [Promise]
+ * Specifies whether the [factory] function returns a [Promise].
  */
  providedAsPromise:boolean;
 
@@ -285,7 +291,9 @@ export class ResolvedBinding {
 }
 
 /**
- * Provides fluent API for imperative construction of [Binding] objects. (JavaScript only.)
+ * Provides an API for imperatively constructing [Binding]s.
+ *
+ * This is only relevant for JavaScript.
  *
  * @exportedAs angular2/di
  */
@@ -294,7 +302,8 @@ export function bind(token):BindingBuilder {
 }
 
 /**
- * Helper class for [bind] function.
+ * Helper class for the [bind] function.
+ *
  * @exportedAs angular2/di
  */
 export class BindingBuilder {
@@ -305,11 +314,11 @@ export class BindingBuilder {
  }
 
  /**
- * Bind an interface to an implementation / subclass.
+ * Binds an interface to an implementation / subclass.
  *
  * ## Example
  *
- * Becuse `toAlias` and `toClass` are often confused the example contains both use cases for easy comparison.
+ * Because `toAlias` and `toClass` are often confused, the example contains both use cases for easy comparison.
  *
  * ```javascript
  *
@@ -338,7 +347,7 @@ export class BindingBuilder {
  }
 
  /**
- * Bind a key to a value.
+ * Binds a key to a value.
  *
  * ## Example
  *
@@ -355,14 +364,14 @@ export class BindingBuilder {
  }
 
  /**
- * Bind a key to an alias of an existing key.
+ * Binds a key to the alias for an existing key.
  *
  * An alias means that we will return the same instance as if the alias token was used. (This is in contrast to
  * `toClass` where a separet instance of `toClass` will be returned.)
  *
  * ## Example
  *
- * Becuse `toAlias` and `toClass` are often confused the example contains both use cases for easy comparison.
+ * Becuse `toAlias` and `toClass` are often confused, the example contains both use cases for easy comparison.
  *
  * ```javascript
  *
@@ -381,7 +390,7 @@ export class BindingBuilder {
  *
  * expect(injectorAlias.get(Vehicle)).toBe(injectorAlias.get(Car));
  * expect(injectorAlias.get(Vehicle) instanceof Car).toBe(true);
-
+ *
  * expect(injectorClass.get(Vehicle)).not.toBe(injectorClass.get(Car));
  * expect(injectorClass.get(Vehicle) instanceof Car).toBe(true);
  * ```
@@ -391,7 +400,7 @@ export class BindingBuilder {
  }
 
  /**
- * Bind a key to a function which computes the value.
+ * Binds a key to a function which computes the value.
  *
  * ## Example
  *
@@ -413,7 +422,7 @@ export class BindingBuilder {
  }
 
  /**
- * Bind a key to a function which computes the value asynchronously.
+ * Binds a key to a function which computes the value asynchronously.
  *
  * ## Example
  *
@@ -429,9 +438,10 @@ export class BindingBuilder {
  * injector.asyncGet(String).then((v) => expect(v).toBe('Value: 3'));
  * ```
  *
- * The interesting thing to note is that event thougt `Numeber` has an async factory, the `String` factory
+ * The interesting thing to note is that event though `Number` has an async factory, the `String` factory
  * function takes the resolved value. This shows that the [Injector] delays executing of the `String` factory
- * until after the `Number` is resolved. This can only be done if the `token` is retrive
+ * until after the `Number` is resolved. This can only be done if the `token` is retrieved using the 
+ * [Injector.asyncGet] API.
  */
  toAsyncFactory(factoryFunction:Function, dependencies:List = null):Binding {
  return new Binding(this.token, {