doc: add some API doc

Closes angular#4060

Author: vicb

modules/angular2/router.ts

@@ -38,6 +38,28 @@ import {CONST_EXPR} from './src/core/facade/lang';
 
 export const ROUTER_DIRECTIVES: any[] = CONST_EXPR([RouterOutlet, RouterLink]);
 
+/**
+ * A list of {@link Binding}. To use the router, you must add this to your application.
+ *
+ * ## Example
+ *
+ * ```typescript
+ * @Component({...})
+ * @View({directives: [ROUTER_DIRECTIVES]})
+ * @RouteConfig([
+ *  new Route(...),
+ * ])
+ * class AppCmp {
+ *  constructor(router: Router, location: Location) {
+ *    // ...
+ *  }
+ *
+ * }
+ *
+ *
+ * bootstrap(AppCmp, [ROUTER_BINDINGS]);
+ * ```
+ */
 export const ROUTER_BINDINGS: any[] = CONST_EXPR([
   RouteRegistry,
   Pipeline,

modules/angular2/src/core/application_tokens.ts

@@ -7,7 +7,8 @@ import {CONST_EXPR} from 'angular2/src/core/facade/lang';
 export const APP_COMPONENT_REF_PROMISE = CONST_EXPR(new OpaqueToken('Promise<ComponentRef>'));
 
 /**
- * An opaque token representing the application root type in the {@link Injector}.
+ * An {@link angular2/di/OpaqueToken} representing the application root type in the {@link
+ * Injector}.
  *
  * ```
  * @Component(...)

modules/angular2/src/core/change_detection/pipe_transform.ts

@@ -1,17 +1,38 @@
 import {ABSTRACT, BaseException, CONST, Type} from 'angular2/src/core/facade/lang';
 
 /**
- * An interface which all pipes must implement.
+ * To create a Pipe, you must implement this interface.
  *
- * #Example
+ * Angular invokes the `transform` method with the subject as the `value` argument and any
+ * parameters in the `args` Array.
+ *
+ * ## Syntax
+ *
+ * `subject | pipeName[:arg0[:arg1...]]`
+ *
+ * ## Example
+ *
+ * The `RepeatPipe` below repeats the subject as many times as indicated by the first argument:
  *
  * ```
- * class DoublePipe implements PipeTransform {
- *  transform(value, args = []) {
- *    return `${value}${value}`;
+ * @Pipe({name: 'repeat'})
+ * class RepeatPipe implements PipeTransform {
+ *
+ *  transform(value: any, args: any[] = []) {
+ *    if (isBlank(args) || args.length == 0) {
+ *      throw new BaseException('limitTo pipe requires one argument');
+ *    }
+ *
+ *    let times: number = args[0];
+ *
+ *    return value.repeat(times);
  *  }
  * }
  * ```
+ *
+ * Invoking `{{ 'ok' | repeat:3 }}` in a template produces `okokok`.
+ *
+ * ```
  */
 export interface PipeTransform { transform(value: any, args: any[]): any; }
 

modules/angular2/src/core/compiler/element_ref.ts

@@ -3,12 +3,11 @@ import {ViewRef} from './view_ref';
 import {RenderViewRef, RenderElementRef, Renderer} from 'angular2/src/core/render/api';
 
 /**
- * Reference to the element.
+ * An opaque reference to the underlying element.
  *
- * Represents an opaque reference to the underlying element. The element is a DOM ELement in
- * a Browser, but may represent other types on other rendering platforms. In the browser the
- * `ElementRef` can be sent to the web-worker. Web Workers can not have references to the
- * DOM Elements.
+ * The underlying native element is a DOM Element in a browser context, but may represent other
+ * types on other rendering platforms. In the browser the `ElementRef` can be sent to the Web
+ * Worker. Web Workers can not have references to the DOM Elements.
  */
 export class ElementRef implements RenderElementRef {
   /**
@@ -51,11 +50,11 @@ export class ElementRef implements RenderElementRef {
   /**
    * Returns the native Element implementation.
    *
-   * In the browser this represents the DOM Element.
+   * In the browser this represents the DOM element.
    *
    * The `nativeElement` can be used as an escape hatch when direct DOM manipulation is needed. Use
-   * this with caution, as it creates tight coupling between your application and the Browser, which
-   * will not work in WebWorkers.
+   * this with caution, as it creates tight coupling between your application and the browser, which
+   * will not work in Web Workers.
    *
    * NOTE: This method will return null in the webworker scenario!
    */

modules/angular2/src/core/di/binding.ts

@@ -266,14 +266,38 @@ export class ResolvedFactory {
 /**
  * Provides an API for imperatively constructing {@link Binding}s.
  *
- * This is only relevant for JavaScript. See {@link BindingBuilder}.
+ * To construct a {@link Binding}, bind a `token` to either a class, a value or a factory function.
+ * See {@link BindingBuilder} for more details.
+ *
+ * The `token` is most commonly an {@link angular2/di/OpaqueToken} or a class.
+ *
+ * `bind` is only relevant for JavaScript. For Dart use the {@link Binding} constructor.
  *
  * ## Example
  *
- * ```javascript
- * bind(MyInterface).toClass(MyClass)
+ * ```typescript
+ * // inj.get(MyClass) would instantiate MyClass
+ * bind(MyClass).toClass(MyClass);
+ *
+ * // inj.get(MyClass) === 'my class'
+ * bind(MyClass).toValue('my class');
  *
+ * // inj.get(MyClass) would instantiate the depenency and call the factory function with the
+ * // instance
+ * bind(MyClass).toFactory(dep => new MyClass(dep), [DepClass]);
+ *
+ * // inj.get(MyOtherClass) === inj.get(MyClass)
+ * bind(MyOtherClass).toAlias(MyClass);
+ * ```
+ *
+ * ```dart
+ * var binding = new Binding(MyClass, toClass: MyClass);
+ * var binding = new Binding(MyClass, toValue: 'my class');
+ * var binding = new Binding(MyClass, toFactory: (dep) => new MyClass(dep),
+ *                           dependencies: [DepClass]);
+ *  var binding = new Binding(MyOtherClass, toAlias: MyClass);
  * ```
+ *
  */
 export function bind(token): BindingBuilder {
   return new BindingBuilder(token);

modules/angular2/src/core/di/injector.ts

@@ -27,9 +27,21 @@ const _MAX_CONSTRUCTION_COUNTER = 10;
 
 export const UNDEFINED: Object = CONST_EXPR(new Object());
 
+/**
+ * Visibility of a {@link Binding}.
+ */
 export enum Visibility {
+  /**
+   * A `Public` {@link Binding} is only visible to regular (as opposed to host) child injectors.
+   */
   Public,
+  /**
+   * A `Private` {@link Binding} is only visible to host (as opposed to regular) child injectors.
+   */
   Private,
+  /**
+   * A `PublicAndPrivate` {@link Binding} is visible to both host and regular child injectors.
+   */
   PublicAndPrivate
 }
 

modules/angular2/src/core/di/opaque_token.ts

@@ -1,10 +1,27 @@
 import {CONST} from 'angular2/src/core/facade/lang';
 
+/**
+ * By binding to an `OpaqueToken` you can enable an application to return more meaningful error
+ * messages.
+ *
+ * ## Example
+ *
+ * ```
+ * // While the following would work, see below for the preferred way
+ * var binding = bind('value0').toValue(0);
+ * ...
+ * var value = injector.get('value0');
+ *
+ * // An OpaqueToken is the preferred way and lead to more helpful error messages
+ * export value0Token = new OpaqueToken('value0');
+ * var binding = bind(value0Token).toValue(0);
+ * ...
+ * var value = injector.get(value0Token);
+ * ```
+ */
 @CONST()
 export class OpaqueToken {
-  _desc: string;
+  constructor(private _desc: string) {}
 
-  constructor(desc: string) { this._desc = 'Token(' + desc + ')'; }
-
-  toString(): string { return this._desc; }
+  toString(): string { return `Token ${this._desc}`; }
 }

modules/angular2/src/core/facade/async.ts

@@ -90,20 +90,46 @@ export class Observable {
 }
 
 /**
+ * Use by directives and components to emit custom {@link Event}s.
+ *
+ * ## Examples
+ *
+ * In the following example, `Zippy` alternatively emits `open` and `close` events when its
+ * title gets clicked:
+ *
+ * ```
+ * @Component({selector: 'zippy'})
+ * @View({template: `
+ *   <div class="zippy">
+ *     <div (click)="toggle()">Toggle</div>
+ *     <div [hidden]="!visible">
+ *       <ng-content></ng-content>
+ *     </div>
+ *  </div>`})
+ * export class Zippy {
+ *   visible: boolean = true;
+ *   @Event() open: EventEmitter = new EventEmitter();
+ *   @Event() close: EventEmitter = new EventEmitter();
+ *
+ *   toggle() {
+ *     this.visible = !this.visible;
+ *     if (this.visible) {
+ *       this.open.next(null);
+ *     } else {
+ *       this.close.next(null);
+ *     }
+ *   }
+ * }
+ * ```
+ *
  * Use Rx.Observable but provides an adapter to make it work as specified here:
  * https://github.com/jhusain/observable-spec
  *
  * Once a reference implementation of the spec is available, switch to it.
  */
 export class EventEmitter extends Observable {
-  _subject: Rx.Subject<any>;
-  _immediateScheduler;
-
-  constructor() {
-    super();
-    this._subject = new Rx.Subject<any>();
-    this._immediateScheduler = (<any>Rx.Scheduler).immediate;
-  }
+  _subject: Rx.Subject<any> = new Rx.Subject<any>();
+  _immediateScheduler = (<any>Rx.Scheduler).immediate;
 
   observer(generator: any): Rx.IDisposable {
     return this._subject.observeOn(this._immediateScheduler)
@@ -114,9 +140,18 @@ export class EventEmitter extends Observable {
 
   toRx(): Rx.Observable<any> { return this._subject; }
 
+  /**
+   * Emits a `value`.
+   */
   next(value: any) { this._subject.onNext(value); }
 
+  /**
+   * Emits an `error`.
+   */
   throw(error: any) { this._subject.onError(error); }
 
+  /**
+   * Closes the stream.
+   */
   return (value?: any) { this._subject.onCompleted(); }
 }

modules/angular2/src/router/router.ts

@@ -27,17 +27,17 @@ let _resolveToTrue = PromiseWrapper.resolve(true);
 let _resolveToFalse = PromiseWrapper.resolve(false);
 
 /**
- * # Router
- * The router is responsible for mapping URLs to components.
+ * The `Router` is responsible for mapping URLs to components.
  *
  * You can see the state of the router by inspecting the read-only field `router.navigating`.
  * This may be useful for showing a spinner, for instance.
  *
  * ## Concepts
+ *
  * Routers and component instances have a 1:1 correspondence.
  *
- * The router holds reference to a number of "outlets." An outlet is a placeholder that the
- * router dynamically fills in depending on the current URL.
+ * The router holds reference to a number of {@link RouterOutlet}.
+ * An outlet is a placeholder that the router dynamically fills in depending on the current URL.
  *
  * When the router navigates from a URL, it must first recognizes it and serialize it into an
  * `Instruction`.