docs: add DI to public docs

Author: mhevery

gulpfile.js

@@ -402,6 +402,7 @@ function createDocsTasks(public) {
       var dgeni = new Dgeni([require(dgeniPackage)]);
       return dgeni.generate();
     } catch(x) {
+      console.log(x);
       console.log(x.stack);
       throw x;
     }

modules/angular2/core.js

@@ -2,7 +2,7 @@
  * @module
  * @public
  * @description
- * Define public API for Angular here.
+ * Define angular core API here.
  */
 export * from './src/core/annotations/visibility';
 export * from './src/core/compiler/interfaces';

modules/angular2/di.js

@@ -1,5 +1,6 @@
 /**
  * @module
+ * @public
  * @description
  * This is a description
  */

modules/angular2/di_annotations.js

@@ -0,0 +1,7 @@
+/**
+ * @module
+ * @public
+ * @description
+ * This is a description
+ */
+

modules/angular2/di_errors.js

@@ -0,0 +1,7 @@
+/**
+ * @module
+ * @public
+ * @description
+ * This is a description
+ */
+

modules/angular2/src/core/annotations/di.js

@@ -30,13 +30,13 @@ export class PropertySetter extends DependencyAnnotation {
  *
  * ## Example
  *
- * suppose we have an `<input>` element and would like to know its `type`.
+ * Suppose we have an `<input>` element and want to know its `type`.
  *
  * ```html
  * <input type="text">
  * ```
  *
- * A decorator could inject string literal `text` like so:
+ * A decorator can inject string literal `text` like so:
  *
  * ```javascript
  * @Decorator({
@@ -71,7 +71,7 @@ export class Attribute extends DependencyAnnotation {
 /**
  * Specifies that a [QueryList] should be injected.
  *
- * See: [QueryList] for usage.
+ * See: [QueryList] for usage and example.
  *
  * @exportedAs angular2/annotations
  */

modules/angular2/src/core/annotations/view.js

@@ -33,38 +33,57 @@ import {ABSTRACT, CONST, Type} from 'angular2/src/facade/lang';
  * @exportedAs angular2/annotations
  */
 export class View {
+  /**
+   * Specify a template URL for an angular component.
+   *
+   * NOTE: either `templateURL` or `template` should be used, but not both.
+   */
   templateUrl:any; //string;
+
+  /**
+   * Specify an inline template for an angular component.
+   *
+   * NOTE: either `templateURL` or `template` should be used, but not both.
+   */
   template:any; //string;
+
+  /**
+   * Specify a list of directives that are active within a template. [TODO: true?]
+   *
+   * Directives must be listed explicitly to provide proper component encapsulation.
+   *
+   * ## Example
+   *
+   * ```javascript
+   * @Component({
+   *     selector: 'my-component'
+   *   })
+   * @View({
+   *   directives: [For]
+   *   template: '
+   *   <ul>
+   *     <li *for="item in items">{{item}}</li>
+   *   </ul>'
+   * })
+   * class MyComponent {
+   * }
+   * ```
+   */
   directives:any; //List<Type>;
-  formatters:any; //List<Type>;
-  source:any;//List<View>;
-  locale:any; //string
-  device:any; //string
+
   @CONST()
   constructor({
       templateUrl,
       template,
-      directives,
-      formatters,
-      source,
-      locale,
-      device
+      directives
     }: {
       templateUrl: string,
       template: string,
-      directives: List<Type>,
-      formatters: List<Type>,
-      source: List<View>,
-      locale: string,
-      device: string
+      directives: List<Type>
     })
   {
     this.templateUrl = templateUrl;
     this.template = template;
     this.directives = directives;
-    this.formatters = formatters;
-    this.source = source;
-    this.locale = locale;
-    this.device = device;
   }
 }

modules/angular2/src/core/life_cycle/life_cycle.js

@@ -26,8 +26,6 @@ import {isPresent} from 'angular2/src/facade/lang';
  *   lifecycle.tick();
  * });
  * ```
- *
- *
  * @exportedAs angular2/change_detection
  */
 @Injectable()

modules/angular2/src/di/annotations.js

@@ -5,10 +5,11 @@ import {CONST} from "angular2/src/facade/lang";
  *
  * ```
  * class AComponent {
- *   constructor(@Inject('aServiceToken') aService) {}
+ *   constructor(@Inject(MyService) aService:MyService) {}
  * }
  * ```
  *
+ * @exportedAs angular2/di_annotations
  */
 export class Inject {
   token;
@@ -23,12 +24,13 @@ export class Inject {
  *
  * ```
  * class AComponent {
- *   constructor(@InjectPromise('aServiceToken') aServicePromise) {
- *     aServicePromise.then(aService => ...);
+ *   constructor(@InjectPromise(MyService) aServicePromise:Promise<MyService>) {
+ *     aServicePromise.then(aService:MyService => ...);
  *   }
  * }
  * ```
  *
+ * @exportedAs angular2/di_annotations
  */
 export class InjectPromise {
   token;
@@ -43,12 +45,13 @@ export class InjectPromise {
  *
  * ```
  * class AComponent {
- *   constructor(@InjectLazy('aServiceToken') aServiceFn) {
- *     aService = aServiceFn();
+ *   constructor(@InjectLazy(MyService) aServiceFn:Function) {
+ *     var aService:MyService = aServiceFn();
  *   }
  * }
  * ```
  *
+ * @exportedAs angular2/di_annotations
  */
 export class InjectLazy {
   token;
@@ -59,16 +62,16 @@ export class InjectLazy {
 }
 
 /**
- * A parameter annotation that marks a dependency as optional.
- *
+ * A parameter annotation that marks a dependency as optional. (Injects `null` if not found.)
  * ```
  * class AComponent {
- *   constructor(@Optional() dp:Dependency) {
- *     this.dp = dp;
+ *   constructor(@Optional() aService:MyService) {
+ *     this.aService = aService;
  *   }
  * }
  * ```
  *
+ * @exportedAs angular2/di_annotations
  */
 export class Optional {
   @CONST()
@@ -102,6 +105,7 @@ export class Optional {
  * The framework can use `new Parent()` to handle the `aService` dependency
  * in a specific way.
  *
+ * @exportedAs angular2/di_annotations
  */
 export class DependencyAnnotation {
   @CONST()
@@ -114,8 +118,8 @@ export class DependencyAnnotation {
 }
 
 /**
- * A class annotation that marks a class as available to `Injector`s for
- * creation.
+ * A marker annotation that marks a class as available to `Injector`s for creation. Used by tooling for generating 
+ * constructor stubs. 
  *
  * ```
  * class NeedsService {
@@ -125,6 +129,7 @@ export class DependencyAnnotation {
  * @Injectable
  * class UsefulService {}
  * ```
+ * @exportedAs angular2/di_annotations
  */
 export class Injectable {
   @CONST()