chore(docs): adding docs to core.ts and annotations.ts

modules/angular2/src/util/decorators.ts

@@ -1,17 +1,77 @@
 import {global, Type, isFunction, stringify} from 'angular2/src/facade/lang';
 
+/**
+ * Declares the interface to be used with {@link Class}.
+ */
 export interface ClassDefinition {
+  /**
+   * Optional argument for specifying the superclass.
+   */
   extends?: Type;
+
+  /**
+   * Required constructor function for a class.
+   *
+   * The function may be optionall wrapped in an `Array`, in which case additional parameter
+   * annotations may be
+   * specified. The number of arguments and the number of paramater annotations must match.
+   *
+   * See {@link Class} for example of usage.
+   */
   constructor: (Function | Array<any>);
 }
 
+/**
+ * An interface implemented by all Angular type decorators, which allows them to be used as ES7
+ * decorators as well as
+ * Angular DSL syntax.
+ *
+ * DSL syntax:
+ *
+ * ```
+ * var MyClass = ng
+ *   .Component({...})
+ *   .View({...})
+ *   .Class({...});
+ * ```
+ *
+ * ES7 syntax:
+ *
+ * ```
+ * @ng.Component({...})
+ * @ng.View({...})
+ * class MyClass {...}
+ * ```
+ */
 export interface TypeDecorator {
-  <T>(cls: T): T;
+  /**
+   * Invoke as ES7 decorator.
+   */
+  <T extends Type>(type: T): T;
+
+  /**
+   * Storage for the accumulated annotations so far used by the DSL syntax.
+   *
+   * Used by {@link Class} to annotate the generated class.
+   */
   annotations: Array<any>;
+
+  /**
+   * Generate a class from the definition and annotate it with {@link TypeDecorator#annotations}.
+   */
   Class(obj: ClassDefinition): Type;
 }
 
-export interface ParamaterDecorator { (cls: Type, unusedKey: any, index: number): void }
+/**
+ * An interface implemented by all Angular parameter decorators, which allows them to be used as ES7
+ * decorators.
+ */
+export interface ParameterDecorator {
+  /**
+   * Invoke as ES7 decorator.
+   */
+  (cls: Type, unusedKey: any, index: number): void
+}
 
 function extractAnnotation(annotation: any): any {
   if (isFunction(annotation) && annotation.hasOwnProperty('annotation')) {
@@ -63,6 +123,87 @@ function applyParams(fnOrArray: (Function | Array<any>), key: string): Function
   }
 }
 
+/**
+ * Provides a way for expressing ES6 classes with parameter annotations in ES5.
+ *
+ * ## Basic Example
+ *
+ * ```
+ * var Greeter = ng.Class({
+ *   constructor: function(name) {
+ *     this.name = name;
+ *   },
+ *
+ *   greet: function() {
+ *     alert('Hello ' + this.name + '!');
+ *   }
+ * });
+ * ```
+ *
+ * is equivalent to ES6:
+ *
+ * ```
+ * class Greeter {
+ *   constructor(name) {
+ *     this.name = name;
+ *   }
+ *
+ *   greet() {
+ *     alert('Hello ' + this.name + '!');
+ *   }
+ * }
+ * ```
+ *
+ * or equivalent to ES5:
+ *
+ * ```
+ * var Greeter = function (name) {
+ *   this.name = name;
+ * }
+ *
+ * Greeter.prototype.greet = function () {
+ *   alert('Hello ' + this.name + '!');
+ * }
+ * ```
+ *
+ * ## Example with parameter annotations
+ *
+ * ```
+ * var MyService = neg.Class({
+ *   constructor: [String, [new Query(), QueryList], function(name, queryList) {
+ *     ...
+ *   }];
+ * });
+ * ```
+ *
+ * is equivalent to ES6:
+ *
+ * ```
+ * class MyService {
+ *   constructor(name: string, @Query() queryList: QueryList) {
+ *     ...
+ *   }
+ * }
+ * ```
+ *
+ * ## Example with inheritance
+ *
+ * ```
+ * var Shape = ng.Class({
+ *   constructor: (color) {
+ *     this.color = color;
+ *   }
+ * });
+ *
+ * var Square = ng.Class({
+ *   extends: Shape,
+ *   constructor: function(color, size) {
+ *     Shape.call(this, color);
+ *     this.size = size;
+ *   }
+ * });
+ * ```
+ */
 export function Class(clsDef: ClassDefinition): Type {
   var constructor = applyParams(
       clsDef.hasOwnProperty('constructor') ? clsDef.constructor : undefined, 'constructor');