docs(core): Myriad of documentation changes including lots of new example code.

modules/angular2/examples/core/di/ts/forward_ref/forward_ref.ts

@@ -0,0 +1,26 @@
+import {Inject, Injector, forwardRef, resolveForwardRef, ForwardRefFn} from 'angular2/core';
+
+// #docregion forward_ref_fn
+var ref = forwardRef(() => Lock);
+// #enddocregion
+
+// #docregion forward_ref
+class Door {
+  lock: Lock;
+  constructor(@Inject(forwardRef(() => Lock)) lock: Lock) { this.lock = lock; }
+}
+
+// Only at this point Lock is defined.
+class Lock {}
+
+var injector = Injector.resolveAndCreate([Door, Lock]);
+var door = injector.get(Door);
+expect(door instanceof Door).toBe(true);
+expect(door.lock instanceof Lock).toBe(true);
+// #enddocregion
+
+// #docregion resolve_forward_ref
+var ref = forwardRef(() => "refValue");
+expect(resolveForwardRef(ref)).toEqual("refValue");
+expect(resolveForwardRef("regularValue")).toEqual("regularValue");
+// #enddocregion

modules/angular2/examples/core/forms/ts/ng_validators/ng_validators.ts

@@ -0,0 +1,10 @@
+import {bootstrap} from 'angular2/bootstrap';
+import {NG_VALIDATORS} from 'angular2/common';
+import {Provider} from 'angular2/core';
+
+let MyApp = null;
+let myValidator = null;
+
+// #docregion ng_validators
+bootstrap(MyApp, [new Provider(NG_VALIDATORS, {useValue: myValidator, multi: true})]);
+// #enddocregion

modules/angular2/examples/core/ts/bootstrap/bootstrap.ts

@@ -0,0 +1,13 @@
+import {Component} from 'angular2/core';
+import {bootstrap} from 'angular2/platform/browser';
+
+// #docregion bootstrap
+@Component({selector: 'my-app', template: 'Hello {{ name }}!'})
+class MyApp {
+  name: string = 'World';
+}
+
+function main() {
+  return bootstrap(MyApp);
+}
+// #enddocregion

modules/angular2/examples/core/ts/metadata/metadata.ts

@@ -0,0 +1,43 @@
+import {Component, Attribute, Directive, Pipe} from 'angular2/core';
+
+var CustomDirective;
+
+// #docregion component
+@Component({selector: 'greet', template: 'Hello {{name}}!', directives: [CustomDirective]})
+class Greet {
+  name: string = 'World';
+}
+// #enddocregion
+
+// #docregion attributeFactory
+@Component({selector: 'page', template: 'Title: {{title}}'})
+class Page {
+  title: string;
+  constructor(@Attribute('title') title: string) { this.title = title; }
+}
+// #enddocregion
+
+// #docregion attributeMetadata
+@Directive({selector: 'input'})
+class InputAttrDirective {
+  constructor(@Attribute('type') type) {
+    // type would be 'text' in this example
+  }
+}
+// #enddocregion
+
+// #docregion directive
+@Directive({selector: 'input'})
+class InputDirective {
+  constructor() {
+    // Add some logic.
+  }
+}
+// #enddocregion
+
+// #docregion pipe
+@Pipe({name: 'lowercase'})
+class Lowercase {
+  transform(v, args) { return v.toLowerCase(); }
+}
+// #enddocregion

modules/angular2/examples/core/ts/platform/platform.ts

@@ -0,0 +1,13 @@
+import {Component, platform} from 'angular2/core';
+import {BROWSER_PROVIDERS, BROWSER_APP_PROVIDERS} from 'angular2/platform/browser';
+
+var appProviders: any[] = [];
+
+// #docregion longform
+@Component({selector: 'my-app', template: 'Hello World'})
+class MyApp {
+}
+
+var app = platform(BROWSER_PROVIDERS).application([BROWSER_APP_PROVIDERS, appProviders]);
+app.bootstrap(MyApp);
+// #enddocregion

modules/angular2/examples/testing/ts/testing.ts

@@ -0,0 +1,90 @@
+import {
+  describe,
+  fdescribe,
+  xdescribe,
+  it,
+  fit,
+  xit,
+  beforeEach,
+  afterEach,
+  beforeEachProviders,
+  inject
+} from 'angular2/testing';
+import {provide} from 'angular2/core';
+
+var db: any;
+class MyService {}
+class MyMockService implements MyService {}
+
+// #docregion describeIt
+describe('some component', () => {
+  it('does something', () => {
+                           // This is a test.
+                       });
+});
+// #enddocregion
+
+// #docregion fdescribe
+fdescribe('some component', () => {
+  it('has a test', () => {
+                       // This test will run.
+                   });
+});
+describe('another component',
+         () => { it('also has a test', () => { throw 'This test will not run.'; }); });
+// #enddocregion
+
+// #docregion xdescribe
+xdescribe('some component', () => { it('has a test', () => {throw 'This test will not run.'}); });
+describe('another component', () => {
+  it('also has a test', () => {
+                            // This test will run.
+                        });
+});
+// #enddocregion
+
+// #docregion fit
+describe('some component', () => {
+  fit('has a test', () => {
+                        // This test will run.
+                    });
+  it('has another test', () => { throw 'This test will not run.'; });
+});
+// #enddocregion
+
+// #docregion xit
+describe('some component', () => {
+  xit('has a test', () => { throw 'This test will not run.'; });
+  it('has another test', () => {
+                             // This test will run.
+                         });
+});
+// #enddocregion
+
+// #docregion beforeEach
+describe('some component', () => {
+  beforeEach(() => { db.connect(); });
+  it('uses the db', () => {
+                        // Database is connected.
+                    });
+});
+// #enddocregion
+
+// #docregion beforeEachProviders
+describe('some component', () => {
+  beforeEachProviders(() => [provide(MyService, {useClass: MyMockService})]);
+  it('uses MyService', inject([MyService], (service) => {
+                                               // service is an instance of MyMockService.
+                                           }));
+});
+// #enddocregion
+
+// #docregion afterEach
+describe('some component', () => {
+  afterEach((done) => { db.reset().then((_) => done()); });
+  it('uses the db', () => {
+                        // This test can leave the database in a dirty state.
+                        // The afterEach will ensure it gets reset.
+                    });
+});
+// #enddocregion

modules/angular2/platform/browser.ts

@@ -62,23 +62,7 @@ export const BROWSER_APP_PROVIDERS: Array<any /*Type | Provider | any[]*/> = CON
  *
  * We can use this script code:
  *
- * ```
+ * {@example core/ts/bootstrap/bootstrap.ts region='bootstrap'}
- * @Component({
- *    selector: 'my-app',
- *    template: 'Hello {{ name }}!'
- * })
- * class MyApp {
- *   name:string;
- *
- *   constructor() {
- *     this.name = 'World';
- *   }
- * }
- *
- * main() {
- *   return bootstrap(MyApp);
- * }
- * ```
  *
  * When the app developer invokes `bootstrap()` with the root component `MyApp` as its
  * argument, Angular performs the following tasks:

modules/angular2/src/common/forms/validators.ts

@@ -13,13 +13,19 @@ import * as modelModule from './model';
  *
  * ### Example
  *
- * ```typescript
+ * {@example core/forms/ts/ng_validators/ng_validators.ts region='ng_validators'}
- * var providers = [
- *   new Provider(NG_VALIDATORS, {useValue: myValidator, multi: true})
- * ];
  * ```
  */
 export const NG_VALIDATORS: OpaqueToken = CONST_EXPR(new OpaqueToken("NgValidators"));
+
+/**
+ * Providers for asynchronous validators to be used for {@link Control}s
+ * in a form.
+ *
+ * Provide this using `multi: true` to add validators.
+ *
+ * See {@link NG_VALIDATORS} for more details.
+ */
 export const NG_ASYNC_VALIDATORS: OpaqueToken = CONST_EXPR(new OpaqueToken("NgAsyncValidators"));
 
 /**

modules/angular2/src/core/application_ref.ts

@@ -173,13 +173,8 @@ export abstract class PlatformRef {
    * typical providers, as shown in the example below.
    *
    * ### Example
-   * ```
-   * var myAppProviders = [MyAppService];
    *
-   * platform()
+   * {@example core/ts/platform/platform.ts region='longform'}
-   *   .application([myAppProviders])
-   *   .bootstrap(MyTopLevelComponent);
-   * ```
    * ### See Also
    *
    * See the {@link bootstrap} documentation for more details.
@@ -315,11 +310,7 @@ export abstract class ApplicationRef {
    * child components under it.
    *
    * ### Example
-   * ```
+   * {@example core/ts/platform/platform.ts region='longform'}
-   * var app = platform.application([appProviders];
-   * app.bootstrap(FirstRootComponent);
-   * app.bootstrap(SecondRootComponent, [provide(OverrideBinding, {useClass: OverriddenBinding})]);
-   * ```
    */
   abstract bootstrap(componentType: Type,
                      providers?: Array<Type | Provider | any[]>): Promise<ComponentRef>;

modules/angular2/src/core/debug/debug_element.ts

@@ -10,6 +10,9 @@ import {ElementRef, ElementRef_} from 'angular2/src/core/linker/element_ref';
  * A DebugElement contains information from the Angular compiler about an
  * element and provides access to the corresponding ElementInjector and
  * underlying DOM Element, as well as a way to query for children.
+ *
+ * A DebugElement can be obtained from a {@link ComponentFixture} or
+ * {@link RootTestComponent}.
  */
 export abstract class DebugElement {
   get componentInstance(): any { return unimplemented(); };
@@ -156,7 +159,7 @@ export class DebugElement_ extends DebugElement {
 }
 
 /**
- * Returns a DebugElement for a ElementRef.
+ * Returns a {@link DebugElement} for an {@link ElementRef}.
  *
  * @param {ElementRef}: elementRef
  * @return {DebugElement}

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

@@ -5,9 +5,7 @@ import {Type, stringify, isFunction} from 'angular2/src/facade/lang';
  *
  * ### Example
  *
- * ```typescript
+ * {@example core/di/ts/forward_ref/forward_ref.ts region='forward_ref_fn'}
- * var fn:ForwardRefFn = forwardRef(() => Lock);
- * ```
  */
 export interface ForwardRefFn { (): any; }
 
@@ -19,25 +17,8 @@ export interface ForwardRefFn { (): any; }
  * but not yet defined. It is also used when the `token` which we use when creating a query is not
  * yet defined.
  *
- * ### Example ([live demo](http://plnkr.co/edit/bRs0SX2OTQiJzqvjgl8P?p=preview))
+ * ### Example
- *
+ * {@example core/di/ts/forward_ref/forward_ref.ts region='forward_ref'}
- * ```typescript
- * class Door {
- *   lock: Lock;
- *   constructor(@Inject(forwardRef(() => Lock)) lock:Lock) {
- *     this.lock = lock;
- *   }
- * }
- *
- * // Only at this point Lock is defined.
- * class Lock {
- * }
- *
- * var injector = Injector.resolveAndCreate([Door, Lock]);
- * var door = injector.get(Door);
- * expect(door instanceof Door).toBe(true);
- * expect(door.lock instanceof Lock).toBe(true);
- * ```
  */
 export function forwardRef(forwardRefFn: ForwardRefFn): Type {
   (<any>forwardRefFn).__forward_ref__ = forwardRef;

modules/angular2/src/core/metadata.ts

@@ -109,16 +109,7 @@ export interface ViewDecorator extends TypeDecorator {
  *
  * ### Example as TypeScript Decorator
  *
- * ```
+ * {@example core/ts/metadata/metadata.ts region='directive'}
- * import {Directive} from "angular2/angular2";
- *
- * @Directive({...})
- * class MyDirective {
- *   constructor() {
- *     ...
- *   }
- * }
- * ```
  *
  * ### Example as ES5 DSL
  *
@@ -178,16 +169,7 @@ export interface DirectiveFactory {
  *
  * ### Example as TypeScript Decorator
  *
- * ```
+ * {@example core/ts/metadata/metadata.ts region='component'}
- * import {Component} from "angular2/angular2";
- *
- * @Component({...})
- * class MyComponent {
- *   constructor() {
- *     ...
- *   }
- * }
- * ```
  *
  * ### Example as ES5 DSL
  *
@@ -334,16 +316,7 @@ export interface ViewFactory {
  *
  * ### Example as TypeScript Decorator
  *
- * ```
+ * {@example core/ts/metadata/metadata.ts region='attributeFactory'}
- * import {Attribute, Component} from "angular2/angular2";
- *
- * @Component({...})
- * class MyComponent {
- *   constructor(@Attribute('title') title: string) {
- *     ...
- *   }
- * }
- * ```
  *
  * ### Example as ES5 DSL
  *
@@ -449,20 +422,9 @@ export interface ViewChildFactory {
 /**
  * {@link PipeMetadata} factory for creating decorators.
  *
- * ### Example as TypeScript Decorator
+ * ### Example
  *
- * ```
+ * {@example core/ts/metadata/metadata.ts region='pipe'}
- * import {Pipe} from "angular2/angular2";
- *
- * @Pipe({...})
- * class MyPipe {
- *   constructor() {
- *     ...
- *   }
- *
- *   transform(v, args) {}
- * }
- * ```
  */
 export interface PipeFactory {
   (obj: {name: string, pure?: boolean}): any;
@@ -530,20 +492,7 @@ export interface HostListenerFactory {
  *
  * ### Example
  *
- * ```
+ * {@example core/ts/metadata/metadata.ts region='component'}
- * @Component({
- *   selector: 'greet',
- *   template: 'Hello {{name}}!'
- * })
- * class Greet {
- *   name: string;
- *
- *   constructor() {
- *     this.name = 'World';
- *   }
- * }
- * ```
- *
  */
 export var Component: ComponentFactory =
     <ComponentFactory>makeDecorator(ComponentMetadata, (fn: any) => fn.View = View);
@@ -962,35 +911,22 @@ export var Directive: DirectiveFactory = <DirectiveFactory>makeDecorator(Directi
 export var View: ViewFactory =
     <ViewFactory>makeDecorator(ViewMetadata, (fn: any) => fn.View = View);
 
-// TODO(alexeagle): remove the duplication of this doc. It is copied from AttributeMetadata.
 /**
- * Metadata properties available for configuring Views.
+ * Specifies that a constant attribute value should be injected.
  *
- * Each Angular component requires a single `@Component` and at least one `@View` annotation. The
+ * The directive can inject constant string literals of host element attributes.
- * `@View` annotation specifies the HTML template to use, and lists the directives that are active
- * within the template.
- *
- * When a component is instantiated, the template is loaded into the component's shadow root, and
- * the expressions and statements in the template are evaluated against the component.
- *
- * For details on the `@Component` annotation, see {@link ComponentMetadata}.
  *
  * ### Example
  *
- * ```
+ * Suppose we have an `<input>` element and want to know its `type`.
- * @Component({
- *   selector: 'greet',
- *   template: 'Hello {{name}}!',
- *   directives: [GreetUser, Bold]
- * })
- * class Greet {
- *   name: string;
  *
- *   constructor() {
+ * ```html
- *     this.name = 'World';
+ * <input type="text">
- *   }
- * }
  * ```
+ *
+ * A decorator can inject string literal `text` like so:
+ *
+ * {@example core/ts/metadata/metadata.ts region='attributeMetadata'}
  */
 export var Attribute: AttributeFactory = makeParamDecorator(AttributeMetadata);
 
@@ -1244,14 +1180,7 @@ export var ViewQuery: QueryFactory = makeParamDecorator(ViewQueryMetadata);
  *
  * ### Example
  *
- * ```
+ * {@example core/ts/metadata/metadata.ts region='pipe'}
- * @Pipe({
- *   name: 'lowercase'
- * })
- * class Lowercase {
- *   transform(v, args) { return v.toLowerCase(); }
- * }
- * ```
  */
 export var Pipe: PipeFactory = <PipeFactory>makeDecorator(PipeMetadata);
 

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

@@ -17,16 +17,7 @@ import {DependencyMetadata} from 'angular2/src/core/di/metadata';
  *
  * A decorator can inject string literal `text` like so:
  *
- * ```javascript
+ * {@example core/ts/metadata/metadata.ts region='attributeMetadata'}
- * @Directive({
- *   selector: `input'
- * })
- * class InputDirective {
- *   constructor(@Attribute('type') type) {
- *     // type would be `text` in this example
- *   }
- * }
- * ```
  */
 @CONST()
 export class AttributeMetadata extends DependencyMetadata {

modules/angular2/src/core/metadata/directives.ts

@@ -804,20 +804,7 @@ export class DirectiveMetadata extends InjectableMetadata {
  *
  * ### Example
  *
- * ```
+ * {@example core/ts/metadata/metadata.ts region='component'}
- * @Component({
- *   selector: 'greet',
- *   template: 'Hello {{name}}!'
- * })
- * class Greet {
- *   name: string;
- *
- *   constructor() {
- *     this.name = 'World';
- *   }
- * }
- * ```
- *
  */
 @CONST()
 export class ComponentMetadata extends DirectiveMetadata {
@@ -954,12 +941,7 @@ export class ComponentMetadata extends DirectiveMetadata {
  *
  * ### Example
  *
- * ```
+ * {@example core/ts/metadata/metadata.ts region='pipe'}
- * @Pipe({name: 'lowercase'})
- * class Lowercase {
- *   transform(v, args) { return v.toLowerCase(); }
- * }
- * ```
  */
 @CONST()
 export class PipeMetadata extends InjectableMetadata {

modules/angular2/src/platform/dom/debug/debug_element_view_listener.ts

@@ -33,6 +33,11 @@ function _getElementId(element): number[] {
   }
 }
 
+/**
+ * Returns a {@link DebugElement} for the given native DOM element, or
+ * null if the given native element does not have an Angular view associated
+ * with it.
+ */
 export function inspectNativeElement(element): DebugElement {
   var elId = _getElementId(element);
   if (isPresent(elId)) {

modules/angular2/src/testing/testing.ts

@@ -20,27 +20,54 @@ export {expect, NgMatchers} from './matchers';
 var _global: jasmine.GlobalPolluter = <any>(typeof window === 'undefined' ? global : window);
 
 /**
- * See http://jasmine.github.io/
+ * Run a function (with an optional asynchronous callback) after each test case.
+ *
+ * See http://jasmine.github.io/ for more details.
+ *
+ * ## Example:
+ *
+ * {@example testing/ts/testing.ts region='afterEach'}
  */
 export var afterEach: Function = _global.afterEach;
 
 /**
- * See http://jasmine.github.io/
+ * Group test cases together under a common description prefix.
+ *
+ * See http://jasmine.github.io/ for more details.
+ *
+ * ## Example:
+ *
+ * {@example testing/ts/testing.ts region='describeIt'}
  */
 export var describe: Function = _global.describe;
 
 /**
- * See http://jasmine.github.io/
+ * See {@link fdescribe}.
  */
 export var ddescribe: Function = _global.fdescribe;
 
 /**
- * See http://jasmine.github.io/
+ * Like {@link describe}, but instructs the test runner to only run
+ * the test cases in this group. This is useful for debugging.
+ *
+ * See http://jasmine.github.io/ for more details.
+ *
+ * ## Example:
+ *
+ * {@example testing/ts/testing.ts region='fdescribe'}
  */
 export var fdescribe: Function = _global.fdescribe;
 
 /**
- * See http://jasmine.github.io/
+ * Like {@link describe}, but instructs the test runner to exclude
+ * this group of test cases from execution. This is useful for
+ * debugging, or for excluding broken tests until they can be fixed.
+ *
+ * See http://jasmine.github.io/ for more details.
+ *
+ * ## Example:
+ *
+ * {@example testing/ts/testing.ts region='xdescribe'}
  */
 export var xdescribe: Function = _global.xdescribe;
 
@@ -68,14 +95,9 @@ jsmBeforeEach(() => {
  *
  * The given function must return a list of DI providers.
  *
- * Example:
+ * ## Example:
  *
- * ```
+ * {@example testing/ts/testing.ts region='beforeEachProviders'}
- *   beforeEachProviders(() => [
- *     bind(Compiler).toClass(MockCompiler),
- *     bind(SomeToken).toValue(myValue),
- *   ]);
- * ```
  */
 export function beforeEachProviders(fn): void {
   jsmBeforeEach(() => {
@@ -171,11 +193,16 @@ function _it(jsmFn: Function, name: string, testFn: FunctionWithParamTokens | An
 
 /**
  * Wrapper around Jasmine beforeEach function.
- * See http://jasmine.github.io/
  *
  * beforeEach may be used with the `inject` function to fetch dependencies.
  * The test will automatically wait for any asynchronous calls inside the
  * injected test function to complete.
+ *
+ * See http://jasmine.github.io/ for more details.
+ *
+ * ## Example:
+ *
+ * {@example testing/ts/testing.ts region='beforeEach'}
  */
 export function beforeEach(fn: FunctionWithParamTokens | AnyTestFn): void {
   if (fn instanceof FunctionWithParamTokens) {
@@ -200,12 +227,18 @@ export function beforeEach(fn: FunctionWithParamTokens | AnyTestFn): void {
 }
 
 /**
- * Wrapper around Jasmine it function.
+ * Define a single test case with the given test name and execution function.
- * See http://jasmine.github.io/
  *
- * it may be used with the `inject` function to fetch dependencies.
+ * The test function can be either a synchronous function, an asynchronous function
- * The test will automatically wait for any asynchronous calls inside the
+ * that takes a completion callback, or an injected function created via {@link inject}
- * injected test function to complete.
+ * or {@link injectAsync}. The test will automatically wait for any asynchronous calls
+ * inside the injected test function to complete.
+ *
+ * Wrapper around Jasmine it function. See http://jasmine.github.io/ for more details.
+ *
+ * ## Example:
+ *
+ * {@example testing/ts/testing.ts region='it'}
  */
 export function it(name: string, fn: FunctionWithParamTokens | AnyTestFn,
                    timeOut: number = null): void {
@@ -213,12 +246,15 @@ export function it(name: string, fn: FunctionWithParamTokens | AnyTestFn,
 }
 
 /**
- * Wrapper around Jasmine xit (skipped it) function.
+ * Like {@link it}, but instructs the test runner to exclude this test
- * See http://jasmine.github.io/
+ * entirely. Useful for debugging or for excluding broken tests until
+ * they can be fixed.
  *
- * it may be used with the `inject` function to fetch dependencies.
+ * Wrapper around Jasmine xit function. See http://jasmine.github.io/ for more details.
- * The test will automatically wait for any asynchronous calls inside the
+ *
- * injected test function to complete.
+ * ## Example:
+ *
+ * {@example testing/ts/testing.ts region='xit'}
  */
 export function xit(name: string, fn: FunctionWithParamTokens | AnyTestFn,
                     timeOut: number = null): void {
@@ -226,12 +262,7 @@ export function xit(name: string, fn: FunctionWithParamTokens | AnyTestFn,
 }
 
 /**
- * Wrapper around Jasmine iit (focused it) function.
+ * See {@link fit}.
- * See http://jasmine.github.io/
- *
- * it may be used with the `inject` function to fetch dependencies.
- * The test will automatically wait for any asynchronous calls inside the
- * injected test function to complete.
  */
 export function iit(name: string, fn: FunctionWithParamTokens | AnyTestFn,
                     timeOut: number = null): void {
@@ -239,12 +270,14 @@ export function iit(name: string, fn: FunctionWithParamTokens | AnyTestFn,
 }
 
 /**
- * Wrapper around Jasmine fit (focused it) function.
+ * Like {@link it}, but instructs the test runner to only run this test.
- * See http://jasmine.github.io/
+ * Useful for debugging.
  *
- * it may be used with the `inject` function to fetch dependencies.
+ * Wrapper around Jasmine fit function. See http://jasmine.github.io/ for more details.
- * The test will automatically wait for any asynchronous calls inside the
+ *
- * injected test function to complete.
+ * ## Example:
+ *
+ * {@example testing/ts/testing.ts region='fit'}
  */
 export function fit(name: string, fn: FunctionWithParamTokens | AnyTestFn,
                     timeOut: number = null): void {