From 80a5e47e61241c2287b162d609f117ea6ae00515 Mon Sep 17 00:00:00 2001
From: Alex Rickabaugh <alx+alxhub@alxandria.net>
Date: Thu, 3 Dec 2015 15:49:09 -0800
Subject: [PATCH] docs(*): Document a lot more symbols that are missing
 comments in our generated docs.

---
 .../common/forms/ts/validators/validators.ts  | 30 +++++++
 .../compiler/ts/url_resolver/url_resolver.ts  | 19 +++++
 .../debug/ts/debug_element/debug_element.ts   | 16 ++++
 .../examples/platform/dom/debug/ts/by/by.ts   | 17 ++++
 .../debug_element_view_listener/providers.ts  | 10 +++
 .../examples/testing/ts/fake_async.ts         | 29 +++++++
 .../angular2/examples/testing/ts/matchers.ts  | 40 ++++++++++
 modules/angular2/http.ts                      |  4 +
 modules/angular2/router.ts                    |  2 +
 .../common/directives/observable_list_diff.ts |  5 ++
 .../directives/control_value_accessor.ts      |  5 ++
 .../forms/directives/ng_control_status.ts     |  4 +
 .../src/common/forms/directives/validators.ts | 24 ++++++
 .../angular2/src/common/forms/form_builder.ts |  2 +
 .../angular2/src/common/forms/validators.ts   |  4 +-
 modules/angular2/src/common/pipes.ts          |  7 ++
 .../angular2/src/common/pipes/common_pipes.ts |  7 ++
 modules/angular2/src/compiler/compiler.ts     |  4 +
 .../src/compiler/directive_metadata.ts        | 12 +++
 .../angular2/src/compiler/source_module.ts    |  6 ++
 modules/angular2/src/compiler/template_ast.ts | 75 +++++++++++++++++-
 .../src/compiler/template_compiler.ts         |  5 ++
 .../angular2/src/compiler/template_parser.ts  |  7 ++
 modules/angular2/src/compiler/url_resolver.ts | 15 +++-
 modules/angular2/src/compiler/xhr.ts          |  4 +
 modules/angular2/src/compiler/xhr_mock.ts     | 24 ++++++
 .../change_detection/change_detection_util.ts |  7 +-
 .../change_detection/change_detector_ref.ts   |  2 +-
 .../src/core/change_detection/constants.ts    | 13 ++++
 .../differs/iterable_differs.ts               |  4 +
 .../differs/keyvalue_differs.ts               |  3 +
 .../angular2/src/core/debug/debug_element.ts  | 59 +++++++++++++-
 modules/angular2/src/core/di/provider.ts      | 11 ++-
 .../src/core/linker/component_url_mapper.ts   |  8 +-
 modules/angular2/src/core/linker/view_ref.ts  |  2 +-
 .../angular2/src/core/linker/view_resolver.ts |  3 +
 modules/angular2/src/core/metadata.ts         | 12 +++
 modules/angular2/src/core/profile/wtf_impl.ts |  3 +
 .../src/core/reflection/reflection.ts         |  4 +
 .../angular2/src/core/reflection/reflector.ts |  7 ++
 modules/angular2/src/core/render/api.ts       | 33 +++++++-
 .../src/core/testability/testability.ts       | 10 +++
 modules/angular2/src/core/zone/ng_zone.ts     |  6 ++
 modules/angular2/src/facade/collection.ts     |  4 +
 modules/angular2/src/facade/exceptions.ts     |  3 +
 modules/angular2/src/facade/lang.ts           |  4 +
 .../angular2/src/http/backends/browser_xhr.ts |  6 +-
 .../src/http/backends/jsonp_backend.ts        | 22 ++++++
 modules/angular2/src/http/http.ts             |  2 +-
 .../src/mock/directive_resolver_mock.ts       |  4 +
 modules/angular2/src/mock/location_mock.ts    |  3 +
 .../angular2/src/mock/mock_application_ref.ts |  3 +
 .../src/mock/mock_location_strategy.ts        |  4 +
 modules/angular2/src/mock/ng_zone_mock.ts     |  3 +
 .../src/platform/browser/browser_adapter.ts   |  3 +
 .../angular2/src/platform/browser_common.ts   | 10 +++
 modules/angular2/src/platform/dom/debug/by.ts | 27 ++++++-
 .../dom/debug/debug_element_view_listener.ts  | 12 +++
 .../src/router/route_config_decorator.ts      |  7 ++
 .../angular2/src/router/route_definition.ts   |  6 ++
 modules/angular2/src/testing/fake_async.ts    | 19 ++++-
 modules/angular2/src/testing/matchers.ts      | 78 ++++++++++++++++++-
 modules/angular2/src/testing/test_injector.ts | 14 +++-
 modules/angular2/src/testing/testing.ts       | 14 +++-
 .../angular2/src/testing/testing_internal.ts  |  3 +
 65 files changed, 793 insertions(+), 22 deletions(-)
 create mode 100644 modules/angular2/examples/common/forms/ts/validators/validators.ts
 create mode 100644 modules/angular2/examples/compiler/ts/url_resolver/url_resolver.ts
 create mode 100644 modules/angular2/examples/core/debug/ts/debug_element/debug_element.ts
 create mode 100644 modules/angular2/examples/platform/dom/debug/ts/by/by.ts
 create mode 100644 modules/angular2/examples/platform/dom/debug/ts/debug_element_view_listener/providers.ts
 create mode 100644 modules/angular2/examples/testing/ts/fake_async.ts
 create mode 100644 modules/angular2/examples/testing/ts/matchers.ts

diff --git a/modules/angular2/examples/common/forms/ts/validators/validators.ts b/modules/angular2/examples/common/forms/ts/validators/validators.ts
new file mode 100644
index 0000000000..6744c8b5ed
--- /dev/null
+++ b/modules/angular2/examples/common/forms/ts/validators/validators.ts
@@ -0,0 +1,30 @@
+import {Component} from 'angular2/core';
+import {MinLengthValidator, MaxLengthValidator} from 'angular2/common';
+
+// #docregion min
+@Component({
+  selector: 'min-cmp',
+  directives: [MinLengthValidator],
+  template: `
+<form>
+  <p>Year: <input ngControl="year" minlength="2"></p>
+</form>
+`
+})
+class MinLengthTestComponent {
+}
+// #enddocregion
+
+// #docregion max
+@Component({
+  selector: 'max-cmp',
+  directives: [MaxLengthValidator],
+  template: `
+<form>
+  <p>Year: <input ngControl="year" maxlength="4"></p>
+</form>
+`
+})
+class MaxLengthTestComponent {
+}
+// #enddocregion
diff --git a/modules/angular2/examples/compiler/ts/url_resolver/url_resolver.ts b/modules/angular2/examples/compiler/ts/url_resolver/url_resolver.ts
new file mode 100644
index 0000000000..3910a38a1a
--- /dev/null
+++ b/modules/angular2/examples/compiler/ts/url_resolver/url_resolver.ts
@@ -0,0 +1,19 @@
+import {provide} from 'angular2/core';
+import {bootstrap} from 'angular2/bootstrap';
+import {UrlResolver} from 'angular2/compiler';
+
+var MyApp;
+
+// #docregion url_resolver
+class MyUrlResolver extends UrlResolver {
+  resolve(baseUrl: string, url: string): string {
+    // Serve CSS files from a special CDN.
+    if (url.substr(-4) === '.css') {
+      return super.resolve('http://cdn.myapp.com/css/', url);
+    }
+    return super.resolve(baseUrl, url);
+  }
+}
+
+bootstrap(MyApp, [provide(UrlResolver, {useClass: MyUrlResolver})]);
+// #enddocregion
diff --git a/modules/angular2/examples/core/debug/ts/debug_element/debug_element.ts b/modules/angular2/examples/core/debug/ts/debug_element/debug_element.ts
new file mode 100644
index 0000000000..ebda75d05c
--- /dev/null
+++ b/modules/angular2/examples/core/debug/ts/debug_element/debug_element.ts
@@ -0,0 +1,16 @@
+import {DebugElement, Scope} from 'angular2/core';
+
+var debugElement: DebugElement;
+var predicate;
+
+// #docregion scope_all
+debugElement.query(predicate, Scope.all);
+// #enddocregion
+
+// #docregion scope_light
+debugElement.query(predicate, Scope.light);
+// #enddocregion
+
+// #docregion scope_view
+debugElement.query(predicate, Scope.view);
+// #enddocregion
diff --git a/modules/angular2/examples/platform/dom/debug/ts/by/by.ts b/modules/angular2/examples/platform/dom/debug/ts/by/by.ts
new file mode 100644
index 0000000000..58c888328c
--- /dev/null
+++ b/modules/angular2/examples/platform/dom/debug/ts/by/by.ts
@@ -0,0 +1,17 @@
+import {By} from 'angular2/platform/browser';
+import {DebugElement, Scope} from 'angular2/core';
+
+var debugElement: DebugElement;
+class MyDirective {}
+
+// #docregion by_all
+debugElement.query(By.all(), Scope.all);
+// #enddocregion
+
+// #docregion by_css
+debugElement.query(By.css('[attribute]'), Scope.all);
+// #enddocregion
+
+// #docregion by_directive
+debugElement.query(By.directive(MyDirective), Scope.all);
+// #enddocregion
diff --git a/modules/angular2/examples/platform/dom/debug/ts/debug_element_view_listener/providers.ts b/modules/angular2/examples/platform/dom/debug/ts/debug_element_view_listener/providers.ts
new file mode 100644
index 0000000000..b9dec70aae
--- /dev/null
+++ b/modules/angular2/examples/platform/dom/debug/ts/debug_element_view_listener/providers.ts
@@ -0,0 +1,10 @@
+import {Component} from 'angular2/core';
+import {bootstrap, ELEMENT_PROBE_PROVIDERS} from 'angular2/platform/browser';
+
+@Component({selector: 'my-component'})
+class MyAppComponent {
+}
+
+// #docregion providers
+bootstrap(MyAppComponent, [ELEMENT_PROBE_PROVIDERS]);
+// #enddocregion
\ No newline at end of file
diff --git a/modules/angular2/examples/testing/ts/fake_async.ts b/modules/angular2/examples/testing/ts/fake_async.ts
new file mode 100644
index 0000000000..55bb766b91
--- /dev/null
+++ b/modules/angular2/examples/testing/ts/fake_async.ts
@@ -0,0 +1,29 @@
+import {describe, it, fakeAsync, expect, tick, clearPendingTimers} from 'angular2/testing';
+
+// #docregion basic
+describe('this test', () => {
+  it('looks async but is synchronous', <any>fakeAsync((): void => {
+       var flag = false;
+       setTimeout(() => { flag = true; }, 100);
+       expect(flag).toBe(false);
+       tick(50);
+       expect(flag).toBe(false);
+       tick(50);
+       expect(flag).toBe(true);
+     }));
+});
+// #enddocregion
+
+// #docregion pending
+describe('this test', () => {
+  it('aborts a timer', <any>fakeAsync((): void => {
+       // This timer is scheduled but doesn't need to complete for the
+       // test to pass (maybe it's a timeout for some operation).
+       // Leaving it will cause the test to fail...
+       setTimeout(() => {}, 100);
+
+       // Unless we clean it up first.
+       clearPendingTimers();
+     }));
+});
+// #enddocregion
\ No newline at end of file
diff --git a/modules/angular2/examples/testing/ts/matchers.ts b/modules/angular2/examples/testing/ts/matchers.ts
new file mode 100644
index 0000000000..f0bf7d2818
--- /dev/null
+++ b/modules/angular2/examples/testing/ts/matchers.ts
@@ -0,0 +1,40 @@
+import {expect} from 'angular2/testing';
+
+var value: any;
+var element: any;
+var exception: any;
+
+abstract class OtherClass {}
+class SomeClass {}
+
+// #docregion toBePromise
+expect(value).toBePromise();
+// #enddocregion
+
+// #docregion toBeAnInstanceOf
+expect(value).toBeAnInstanceOf(SomeClass);
+// #enddocregion
+
+// #docregion toHaveText
+expect(element).toHaveText('Hello world!');
+// #enddocregion
+
+// #docregion toHaveCssClass
+expect(element).toHaveCssClass('current');
+// #enddocregion
+
+// #docregion toHaveCssStyle
+expect(element).toHaveCssStyle({width: '100px', height: 'auto'});
+// #enddocregion
+
+// #docregion toContainError
+expect(exception).toContainError('Failed to load');
+// #enddocregion
+
+// #docregion toThrowErrorWith
+expect(() => { throw 'Failed to load'; }).toThrowErrorWith('Failed to load');
+// #enddocregion
+
+// #docregion toImplement
+expect(SomeClass).toImplement(OtherClass);
+// #enddocregion
diff --git a/modules/angular2/http.ts b/modules/angular2/http.ts
index 69c918d4ee..5341e23191 100644
--- a/modules/angular2/http.ts
+++ b/modules/angular2/http.ts
@@ -166,6 +166,8 @@ export const HTTP_PROVIDERS: any[] = [
 ];
 
 /**
+ * See {@link HTTP_PROVIDERS} instead.
+ *
  * @deprecated
  */
 export const HTTP_BINDINGS = HTTP_PROVIDERS;
@@ -291,6 +293,8 @@ export const JSONP_PROVIDERS: any[] = [
 ];
 
 /**
+ * See {@link JSONP_PROVIDERS} instead.
+ *
  * @deprecated
  */
 export const JSON_BINDINGS = JSONP_PROVIDERS;
diff --git a/modules/angular2/router.ts b/modules/angular2/router.ts
index 8d5409952d..4cea18950a 100644
--- a/modules/angular2/router.ts
+++ b/modules/angular2/router.ts
@@ -98,6 +98,8 @@ export const ROUTER_PROVIDERS: any[] = CONST_EXPR([
 ]);
 
 /**
+ * Use {@link ROUTER_PROVIDERS} instead.
+ *
  * @deprecated
  */
 export const ROUTER_BINDINGS = ROUTER_PROVIDERS;
diff --git a/modules/angular2/src/common/directives/observable_list_diff.ts b/modules/angular2/src/common/directives/observable_list_diff.ts
index 08d07c5007..ee99cf4047 100644
--- a/modules/angular2/src/common/directives/observable_list_diff.ts
+++ b/modules/angular2/src/common/directives/observable_list_diff.ts
@@ -2,4 +2,9 @@
 
 // I need to be here to make TypeScript think this is a module.
 import {} from 'angular2/src/facade/lang';
+
+/**
+ * This module exists in Dart, but not in Typescript. This exported symbol
+ * is only here to help Typescript think this is a module.
+ */
 export var workaround_empty_observable_list_diff: any;
diff --git a/modules/angular2/src/common/forms/directives/control_value_accessor.ts b/modules/angular2/src/common/forms/directives/control_value_accessor.ts
index 33a907ba62..90820f7d70 100644
--- a/modules/angular2/src/common/forms/directives/control_value_accessor.ts
+++ b/modules/angular2/src/common/forms/directives/control_value_accessor.ts
@@ -26,4 +26,9 @@ export interface ControlValueAccessor {
   registerOnTouched(fn: any): void;
 }
 
+/**
+ * Used to provide a {@link ControlValueAccessor} for form controls.
+ *
+ * See {@link DefaultValueAccessor} for how to implement one.
+ */
 export const NG_VALUE_ACCESSOR: OpaqueToken = CONST_EXPR(new OpaqueToken("NgValueAccessor"));
\ No newline at end of file
diff --git a/modules/angular2/src/common/forms/directives/ng_control_status.ts b/modules/angular2/src/common/forms/directives/ng_control_status.ts
index 39f07e6ea4..38b7ccdabb 100644
--- a/modules/angular2/src/common/forms/directives/ng_control_status.ts
+++ b/modules/angular2/src/common/forms/directives/ng_control_status.ts
@@ -2,6 +2,10 @@ import {Directive, Self} from 'angular2/core';
 import {NgControl} from './ng_control';
 import {isBlank, isPresent} from 'angular2/src/facade/lang';
 
+/**
+ * Directive automatically applied to Angular forms that sets CSS classes
+ * based on control status (valid/invalid/dirty/etc).
+ */
 @Directive({
   selector: '[ngControl],[ngModel],[ngFormControl]',
   host: {
diff --git a/modules/angular2/src/common/forms/directives/validators.ts b/modules/angular2/src/common/forms/directives/validators.ts
index 53ca2ae56a..dcb3189bcc 100644
--- a/modules/angular2/src/common/forms/directives/validators.ts
+++ b/modules/angular2/src/common/forms/directives/validators.ts
@@ -45,8 +45,20 @@ const REQUIRED_VALIDATOR =
 export class RequiredValidator {
 }
 
+/**
+ * Provivder which adds {@link MinLengthValidator} to {@link NG_VALIDATORS}.
+ *
+ * ## Example:
+ *
+ * {@example common/forms/ts/validators/validators.ts region='min'}
+ */
 const MIN_LENGTH_VALIDATOR = CONST_EXPR(
     new Provider(NG_VALIDATORS, {useExisting: forwardRef(() => MinLengthValidator), multi: true}));
+
+/**
+ * A directive which installs the {@link MinLengthValidator} for any `ngControl`,
+ * `ngFormControl`, or control with `ngModel` that also has a `minlength` attribute.
+ */
 @Directive({
   selector: '[minlength][ngControl],[minlength][ngFormControl],[minlength][ngModel]',
   providers: [MIN_LENGTH_VALIDATOR]
@@ -61,8 +73,20 @@ export class MinLengthValidator implements Validator {
   validate(c: Control): {[key: string]: any} { return this._validator(c); }
 }
 
+/**
+ * Provider which adds {@link MaxLengthValidator} to {@link NG_VALIDATORS}.
+ *
+ * ## Example:
+ *
+ * {@example common/forms/ts/validators/validators.ts region='max'}
+ */
 const MAX_LENGTH_VALIDATOR = CONST_EXPR(
     new Provider(NG_VALIDATORS, {useExisting: forwardRef(() => MaxLengthValidator), multi: true}));
+
+/**
+ * A directive which installs the {@link MaxLengthValidator} for any `ngControl, `ngFormControl`,
+ * or control with `ngModel` that also has a `maxlength` attribute.
+ */
 @Directive({
   selector: '[maxlength][ngControl],[maxlength][ngFormControl],[maxlength][ngModel]',
   providers: [MAX_LENGTH_VALIDATOR]
diff --git a/modules/angular2/src/common/forms/form_builder.ts b/modules/angular2/src/common/forms/form_builder.ts
index 11f415b335..b6ef3fdc7c 100644
--- a/modules/angular2/src/common/forms/form_builder.ts
+++ b/modules/angular2/src/common/forms/form_builder.ts
@@ -119,6 +119,8 @@ export class FormBuilder {
 export const FORM_PROVIDERS: Type[] = CONST_EXPR([FormBuilder]);
 
 /**
+ * See {@link FORM_PROVIDERS} instead.
+ *
  * @deprecated
  */
 export const FORM_BINDINGS = FORM_PROVIDERS;
diff --git a/modules/angular2/src/common/forms/validators.ts b/modules/angular2/src/common/forms/validators.ts
index ee8bc60dad..f9cdc1c647 100644
--- a/modules/angular2/src/common/forms/validators.ts
+++ b/modules/angular2/src/common/forms/validators.ts
@@ -14,7 +14,6 @@ import * as modelModule from './model';
  * ### Example
  *
  * {@example core/forms/ts/ng_validators/ng_validators.ts region='ng_validators'}
- * ```
  */
 export const NG_VALIDATORS: OpaqueToken = CONST_EXPR(new OpaqueToken("NgValidators"));
 
@@ -32,8 +31,7 @@ export const NG_ASYNC_VALIDATORS: OpaqueToken = CONST_EXPR(new OpaqueToken("NgAs
  * Provides a set of validators used by form controls.
  *
  * A validator is a function that processes a {@link Control} or collection of
- * controls and returns a {@link StringMap} of errors. A null map means that
- * validation has passed.
+ * controls and returns a map of errors. A null map means that validation has passed.
  *
  * ### Example
  *
diff --git a/modules/angular2/src/common/pipes.ts b/modules/angular2/src/common/pipes.ts
index 93950e9a9d..7c7a25c1ef 100644
--- a/modules/angular2/src/common/pipes.ts
+++ b/modules/angular2/src/common/pipes.ts
@@ -20,6 +20,13 @@ export {LowerCasePipe} from './pipes/lowercase_pipe';
 export {NumberPipe, DecimalPipe, PercentPipe, CurrencyPipe} from './pipes/number_pipe';
 export {UpperCasePipe} from './pipes/uppercase_pipe';
 
+/**
+ * A collection of Angular core pipes that are likely to be used in each and every
+ * application.
+ *
+ * This collection can be used to quickly enumerate all the built-in pipes in the `pipes`
+ * property of the `@Component` or `@View` decorators.
+ */
 export const COMMON_PIPES = CONST_EXPR([
   AsyncPipe,
   UpperCasePipe,
diff --git a/modules/angular2/src/common/pipes/common_pipes.ts b/modules/angular2/src/common/pipes/common_pipes.ts
index 7773c9332f..ac6dc36c09 100644
--- a/modules/angular2/src/common/pipes/common_pipes.ts
+++ b/modules/angular2/src/common/pipes/common_pipes.ts
@@ -12,6 +12,13 @@ import {DatePipe} from './date_pipe';
 import {DecimalPipe, PercentPipe, CurrencyPipe} from './number_pipe';
 import {CONST_EXPR} from 'angular2/src/facade/lang';
 
+/**
+ * A collection of Angular core pipes that are likely to be used in each and every
+ * application.
+ *
+ * This collection can be used to quickly enumerate all the built-in pipes in the `pipes`
+ * property of the `@Component` or `@View` decorators.
+ */
 export const COMMON_PIPES = CONST_EXPR([
   AsyncPipe,
   UpperCasePipe,
diff --git a/modules/angular2/src/compiler/compiler.ts b/modules/angular2/src/compiler/compiler.ts
index 76a112f879..c35bc9104c 100644
--- a/modules/angular2/src/compiler/compiler.ts
+++ b/modules/angular2/src/compiler/compiler.ts
@@ -31,6 +31,10 @@ function _createChangeDetectorGenConfig() {
   return new ChangeDetectorGenConfig(assertionsEnabled(), false, true);
 }
 
+/**
+ * A set of providers that provide `RuntimeCompiler` and its dependencies to use for
+ * template compilation.
+ */
 export const COMPILER_PROVIDERS: Array<Type | Provider | any[]> = CONST_EXPR([
   Lexer,
   Parser,
diff --git a/modules/angular2/src/compiler/directive_metadata.ts b/modules/angular2/src/compiler/directive_metadata.ts
index 5033a183cb..f82f6b031a 100644
--- a/modules/angular2/src/compiler/directive_metadata.ts
+++ b/modules/angular2/src/compiler/directive_metadata.ts
@@ -21,6 +21,9 @@ import {LifecycleHooks, LIFECYCLE_HOOKS_VALUES} from 'angular2/src/core/linker/i
 // group 2: "event" from "(event)"
 var HOST_REG_EXP = /^(?:(?:\[([^\]]+)\])|(?:\(([^\)]+)\)))$/g;
 
+/**
+ * Metadata regarding compilation of a type.
+ */
 export class CompileTypeMetadata {
   runtime: Type;
   name: string;
@@ -49,6 +52,9 @@ export class CompileTypeMetadata {
   }
 }
 
+/**
+ * Metadata regarding compilation of a template.
+ */
 export class CompileTemplateMetadata {
   encapsulation: ViewEncapsulation;
   template: string;
@@ -98,6 +104,9 @@ export class CompileTemplateMetadata {
   }
 }
 
+/**
+ * Metadata regarding compilation of a directive.
+ */
 export class CompileDirectiveMetadata {
   static create({type, isComponent, dynamicLoadable, selector, exportAs, changeDetection, inputs,
                  outputs, host, lifecycleHooks, template}: {
@@ -250,6 +259,9 @@ export class CompileDirectiveMetadata {
   }
 }
 
+/**
+ * Construct {@link CompileDirectiveMetadata} from {@link ComponentTypeMetadata} and a selector.
+ */
 export function createHostComponentMeta(componentType: CompileTypeMetadata,
                                         componentSelector: string): CompileDirectiveMetadata {
   var template = CssSelector.parse(componentSelector)[0].getMatchingElementTemplate();
diff --git a/modules/angular2/src/compiler/source_module.ts b/modules/angular2/src/compiler/source_module.ts
index 4a5c8be44d..49dc23a9bf 100644
--- a/modules/angular2/src/compiler/source_module.ts
+++ b/modules/angular2/src/compiler/source_module.ts
@@ -6,6 +6,9 @@ export function moduleRef(moduleUrl): string {
   return `#MODULE[${moduleUrl}]`;
 }
 
+/**
+ * Represents generated source code with module references. Internal to the Angular compiler.
+ */
 export class SourceModule {
   constructor(public moduleUrl: string, public sourceWithModuleRefs: string) {}
 
@@ -39,6 +42,9 @@ export class SourceExpressions {
   constructor(public declarations: string[], public expressions: string[]) {}
 }
 
+/**
+ * Represents generated source code with imports. Internal to the Angular compiler.
+ */
 export class SourceWithImports {
   constructor(public source: string, public imports: string[][]) {}
 }
diff --git a/modules/angular2/src/compiler/template_ast.ts b/modules/angular2/src/compiler/template_ast.ts
index 8c31180f96..1b79d32be5 100644
--- a/modules/angular2/src/compiler/template_ast.ts
+++ b/modules/angular2/src/compiler/template_ast.ts
@@ -3,17 +3,33 @@ import {isPresent} from 'angular2/src/facade/lang';
 import {CompileDirectiveMetadata} from './directive_metadata';
 import {ParseSourceSpan} from './parse_util';
 
+/**
+ * An Abstract Syntax Tree node representing part of a parsed Angular template.
+ */
 export interface TemplateAst {
+  /**
+   * The source span from which this node was parsed.
+   */
   sourceSpan: ParseSourceSpan;
+
+  /**
+   * Visit this node and possibly transform it.
+   */
   visit(visitor: TemplateAstVisitor, context: any): any;
 }
 
+/**
+ * A segment of text within the template.
+ */
 export class TextAst implements TemplateAst {
   constructor(public value: string, public ngContentIndex: number,
               public sourceSpan: ParseSourceSpan) {}
   visit(visitor: TemplateAstVisitor, context: any): any { return visitor.visitText(this, context); }
 }
 
+/**
+ * A bound expression within the text of a template.
+ */
 export class BoundTextAst implements TemplateAst {
   constructor(public value: AST, public ngContentIndex: number,
               public sourceSpan: ParseSourceSpan) {}
@@ -22,11 +38,17 @@ export class BoundTextAst implements TemplateAst {
   }
 }
 
+/**
+ * A plain attribute on an element.
+ */
 export class AttrAst implements TemplateAst {
   constructor(public name: string, public value: string, public sourceSpan: ParseSourceSpan) {}
   visit(visitor: TemplateAstVisitor, context: any): any { return visitor.visitAttr(this, context); }
 }
 
+/**
+ * A binding for an element property (e.g. `[property]="expression"`).
+ */
 export class BoundElementPropertyAst implements TemplateAst {
   constructor(public name: string, public type: PropertyBindingType, public value: AST,
               public unit: string, public sourceSpan: ParseSourceSpan) {}
@@ -35,6 +57,9 @@ export class BoundElementPropertyAst implements TemplateAst {
   }
 }
 
+/**
+ * A binding for an element event (e.g. `(event)="handler()"`).
+ */
 export class BoundEventAst implements TemplateAst {
   constructor(public name: string, public target: string, public handler: AST,
               public sourceSpan: ParseSourceSpan) {}
@@ -50,6 +75,9 @@ export class BoundEventAst implements TemplateAst {
   }
 }
 
+/**
+ * A variable declaration on an element (e.g. `#var="expression"`).
+ */
 export class VariableAst implements TemplateAst {
   constructor(public name: string, public value: string, public sourceSpan: ParseSourceSpan) {}
   visit(visitor: TemplateAstVisitor, context: any): any {
@@ -57,6 +85,9 @@ export class VariableAst implements TemplateAst {
   }
 }
 
+/**
+ * An element declaration in a template.
+ */
 export class ElementAst implements TemplateAst {
   constructor(public name: string, public attrs: AttrAst[],
               public inputs: BoundElementPropertyAst[], public outputs: BoundEventAst[],
@@ -67,11 +98,17 @@ export class ElementAst implements TemplateAst {
     return visitor.visitElement(this, context);
   }
 
+  /**
+   * Whether the element has any active bindings (inputs, outputs, vars, or directives).
+   */
   isBound(): boolean {
     return (this.inputs.length > 0 || this.outputs.length > 0 || this.exportAsVars.length > 0 ||
             this.directives.length > 0);
   }
 
+  /**
+   * Get the component associated with this element, if any.
+   */
   getComponent(): CompileDirectiveMetadata {
     return this.directives.length > 0 && this.directives[0].directive.isComponent ?
                this.directives[0].directive :
@@ -79,6 +116,9 @@ export class ElementAst implements TemplateAst {
   }
 }
 
+/**
+ * A `<template>` element included in an Angular template.
+ */
 export class EmbeddedTemplateAst implements TemplateAst {
   constructor(public attrs: AttrAst[], public outputs: BoundEventAst[], public vars: VariableAst[],
               public directives: DirectiveAst[], public children: TemplateAst[],
@@ -88,6 +128,9 @@ export class EmbeddedTemplateAst implements TemplateAst {
   }
 }
 
+/**
+ * A directive property with a bound value (e.g. `*ngIf="condition").
+ */
 export class BoundDirectivePropertyAst implements TemplateAst {
   constructor(public directiveName: string, public templateName: string, public value: AST,
               public sourceSpan: ParseSourceSpan) {}
@@ -96,6 +139,9 @@ export class BoundDirectivePropertyAst implements TemplateAst {
   }
 }
 
+/**
+ * A directive declared on an element.
+ */
 export class DirectiveAst implements TemplateAst {
   constructor(public directive: CompileDirectiveMetadata,
               public inputs: BoundDirectivePropertyAst[],
@@ -106,6 +152,9 @@ export class DirectiveAst implements TemplateAst {
   }
 }
 
+/**
+ * Position where content is to be projected (instance of `<ng-content>` in a template).
+ */
 export class NgContentAst implements TemplateAst {
   constructor(public index: number, public ngContentIndex: number,
               public sourceSpan: ParseSourceSpan) {}
@@ -114,13 +163,35 @@ export class NgContentAst implements TemplateAst {
   }
 }
 
+/**
+ * Enumeration of types of property bindings.
+ */
 export enum PropertyBindingType {
+
+  /**
+   * A normal binding to a property (e.g. `[property]="expression"`).
+   */
   Property,
+
+  /**
+   * A binding to an element attribute (e.g. `[attr.name]="expression"`).
+   */
   Attribute,
+
+  /**
+   * A binding to a CSS class (e.g. `[class.name]="condition"`).
+   */
   Class,
+
+  /**
+   * A binding to a style rule (e.g. `[style.rule]="expression"`).
+   */
   Style
 }
 
+/**
+ * A visitor for {@link TemplateAst} trees that will process each node.
+ */
 export interface TemplateAstVisitor {
   visitNgContent(ast: NgContentAst, context: any): any;
   visitEmbeddedTemplate(ast: EmbeddedTemplateAst, context: any): any;
@@ -135,7 +206,9 @@ export interface TemplateAstVisitor {
   visitDirectiveProperty(ast: BoundDirectivePropertyAst, context: any): any;
 }
 
-
+/**
+ * Visit every node in a list of {@link TemplateAst}s with the given {@link TemplateAstVisitor}.
+ */
 export function templateVisitAll(visitor: TemplateAstVisitor, asts: TemplateAst[],
                                  context: any = null): any[] {
   var result = [];
diff --git a/modules/angular2/src/compiler/template_compiler.ts b/modules/angular2/src/compiler/template_compiler.ts
index 0da1186602..06b6300000 100644
--- a/modules/angular2/src/compiler/template_compiler.ts
+++ b/modules/angular2/src/compiler/template_compiler.ts
@@ -32,6 +32,11 @@ import {
   MODULE_SUFFIX
 } from './util';
 
+/**
+ * An internal module of the Angular compiler that begins with component types,
+ * extracts templates, and eventually produces a compiled version of the component
+ * ready for linking into an application.
+ */
 @Injectable()
 export class TemplateCompiler {
   private _hostCacheKeys = new Map<Type, any>();
diff --git a/modules/angular2/src/compiler/template_parser.ts b/modules/angular2/src/compiler/template_parser.ts
index 32a69f58b1..8e9a5f1bb3 100644
--- a/modules/angular2/src/compiler/template_parser.ts
+++ b/modules/angular2/src/compiler/template_parser.ts
@@ -69,6 +69,13 @@ const STYLE_PREFIX = 'style';
 
 var TEXT_CSS_SELECTOR = CssSelector.parse('*')[0];
 
+/**
+ * Provides an array of {@link TemplateAstVisitor}s which will be used to transform
+ * parsed templates before compilation is invoked, allowing custom expression syntax
+ * and other advanced transformations.
+ *
+ * This is currently an internal-only feature and not meant for general use.
+ */
 export const TEMPLATE_TRANSFORMS = CONST_EXPR(new OpaqueToken('TemplateTransforms'));
 
 export class TemplateParseError extends ParseError {
diff --git a/modules/angular2/src/compiler/url_resolver.ts b/modules/angular2/src/compiler/url_resolver.ts
index 7c914f5348..9174f8ddfb 100644
--- a/modules/angular2/src/compiler/url_resolver.ts
+++ b/modules/angular2/src/compiler/url_resolver.ts
@@ -11,18 +11,28 @@ import {ListWrapper} from 'angular2/src/facade/collection';
 import {PACKAGE_ROOT_URL} from 'angular2/src/core/application_tokens';
 import {Provider} from 'angular2/src/core/di';
 
+/**
+ * Create a {@link UrlResolver} with no package prefix.
+ */
 export function createWithoutPackagePrefix(): UrlResolver {
   return new UrlResolver();
 }
 
+/**
+ * A default provider for {@link PACKAGE_ROOT_URL} that maps to '/'.
+ */
 export var DEFAULT_PACKAGE_URL_PROVIDER = new Provider(PACKAGE_ROOT_URL, {useValue: "/"});
 
 /**
  * Used by the {@link Compiler} when resolving HTML and CSS template URLs.
  *
- * This interface can be overridden by the application developer to create custom behavior.
+ * This class can be overridden by the application developer to create custom behavior.
  *
  * See {@link Compiler}
+ *
+ * ## Example
+ *
+ * {@example compiler/ts/url_resolver/url_resolver.ts region='url_resolver'}
  */
 @Injectable()
 export class UrlResolver {
@@ -58,6 +68,9 @@ export class UrlResolver {
   }
 }
 
+/**
+ * Extract the scheme of a URL.
+ */
 export function getUrlScheme(url: string): string {
   var match = _split(url);
   return (match && match[_ComponentIndex.Scheme]) || "";
diff --git a/modules/angular2/src/compiler/xhr.ts b/modules/angular2/src/compiler/xhr.ts
index 43253a7295..6eb5d6a604 100644
--- a/modules/angular2/src/compiler/xhr.ts
+++ b/modules/angular2/src/compiler/xhr.ts
@@ -1,6 +1,10 @@
 import {Promise} from 'angular2/src/facade/async';
 
 // TODO: vsavkin rename it into TemplateLoader
+/**
+ * An interface for retrieving documents by URL that the compiler uses
+ * to load templates.
+ */
 export class XHR {
   get(url: string): Promise<string> { return null; }
 }
diff --git a/modules/angular2/src/compiler/xhr_mock.ts b/modules/angular2/src/compiler/xhr_mock.ts
index 7c92d81110..72e766ab39 100644
--- a/modules/angular2/src/compiler/xhr_mock.ts
+++ b/modules/angular2/src/compiler/xhr_mock.ts
@@ -4,6 +4,10 @@ import {isBlank, isPresent, normalizeBlank} from 'angular2/src/facade/lang';
 import {BaseException, WrappedException} from 'angular2/src/facade/exceptions';
 import {PromiseCompleter, PromiseWrapper, Promise} from 'angular2/src/facade/async';
 
+/**
+ * A mock implemenation of {@link XHR} that allows outgoing requests to be mocked
+ * and responded to within a single test, without going to the network.
+ */
 export class MockXHR extends XHR {
   private _expectations: _Expectation[] = [];
   private _definitions = new Map<string, string>();
@@ -15,13 +19,30 @@ export class MockXHR extends XHR {
     return request.getPromise();
   }
 
+  /**
+   * Add an expectation for the given URL. Incoming requests will be checked against
+   * the next expectation (in FIFO order). The `verifyNoOutstandingExpectations` method
+   * can be used to check if any expectations have not yet been met.
+   *
+   * The response given will be returned if the expectation matches.
+   */
   expect(url: string, response: string) {
     var expectation = new _Expectation(url, response);
     this._expectations.push(expectation);
   }
 
+  /**
+   * Add a definition for the given URL to return the given response. Unlike expectations,
+   * definitions have no order and will satisfy any matching request at any time. Also
+   * unlike expectations, unused definitions do not cause `verifyNoOutstandingExpectations`
+   * to return an error.
+   */
   when(url: string, response: string) { this._definitions.set(url, response); }
 
+  /**
+   * Process pending requests and verify there are no outstanding expectations. Also fails
+   * if no requests are pending.
+   */
   flush() {
     if (this._requests.length === 0) {
       throw new BaseException('No pending requests to flush');
@@ -34,6 +55,9 @@ export class MockXHR extends XHR {
     this.verifyNoOutstandingExpectations();
   }
 
+  /**
+   * Throw an exception if any expectations have not been satisfied.
+   */
   verifyNoOutstandingExpectations() {
     if (this._expectations.length === 0) return;
 
diff --git a/modules/angular2/src/core/change_detection/change_detection_util.ts b/modules/angular2/src/core/change_detection/change_detection_util.ts
index 8d65100077..fd99a44fa8 100644
--- a/modules/angular2/src/core/change_detection/change_detection_util.ts
+++ b/modules/angular2/src/core/change_detection/change_detection_util.ts
@@ -54,10 +54,15 @@ var _wrappedValues = [
 
 var _wrappedIndex = 0;
 
-
+/**
+ * Represents a basic change from a previous to a new value.
+ */
 export class SimpleChange {
   constructor(public previousValue: any, public currentValue: any) {}
 
+  /**
+   * Check whether the new value is the first value assigned.
+   */
   isFirstChange(): boolean { return this.previousValue === ChangeDetectionUtil.uninitialized; }
 }
 
diff --git a/modules/angular2/src/core/change_detection/change_detector_ref.ts b/modules/angular2/src/core/change_detection/change_detector_ref.ts
index cee17767c5..e128dcaac2 100644
--- a/modules/angular2/src/core/change_detection/change_detector_ref.ts
+++ b/modules/angular2/src/core/change_detection/change_detector_ref.ts
@@ -122,7 +122,7 @@ export abstract class ChangeDetectorRef {
    * check
    * every five seconds.
    *
-   * See {@link detach} for more information.
+   * See {@link ChangeDetectorRef#detach} for more information.
    */
   abstract detectChanges(): void;
 
diff --git a/modules/angular2/src/core/change_detection/constants.ts b/modules/angular2/src/core/change_detection/constants.ts
index de23c92667..e28f89e559 100644
--- a/modules/angular2/src/core/change_detection/constants.ts
+++ b/modules/angular2/src/core/change_detection/constants.ts
@@ -1,5 +1,8 @@
 import {StringWrapper, normalizeBool, isBlank} from 'angular2/src/facade/lang';
 
+/**
+ * Describes the current state of the change detector.
+ */
 export enum ChangeDetectorState {
   /**
    * `NeverChecked` means that the change detector has not been checked yet, and
@@ -21,6 +24,10 @@ export enum ChangeDetectorState {
   Errored
 }
 
+/**
+ * Describes within the change detector which strategy will be used the next time change
+ * detection is triggered.
+ */
 export enum ChangeDetectionStrategy {
   /**
    * `CheckedOnce` means that after calling detectChanges the mode of the change detector
@@ -62,6 +69,9 @@ export enum ChangeDetectionStrategy {
   OnPushObserve
 }
 
+/**
+ * List of possible {@link ChangeDetectionStrategy} values.
+ */
 export var CHANGE_DETECTION_STRATEGY_VALUES = [
   ChangeDetectionStrategy.CheckOnce,
   ChangeDetectionStrategy.Checked,
@@ -72,6 +82,9 @@ export var CHANGE_DETECTION_STRATEGY_VALUES = [
   ChangeDetectionStrategy.OnPushObserve
 ];
 
+/**
+ * List of possible {@link ChangeDetectorState} values.
+ */
 export var CHANGE_DETECTOR_STATE_VALUES = [
   ChangeDetectorState.NeverChecked,
   ChangeDetectorState.CheckedBefore,
diff --git a/modules/angular2/src/core/change_detection/differs/iterable_differs.ts b/modules/angular2/src/core/change_detection/differs/iterable_differs.ts
index c6a69084d9..076ac40e58 100644
--- a/modules/angular2/src/core/change_detection/differs/iterable_differs.ts
+++ b/modules/angular2/src/core/change_detection/differs/iterable_differs.ts
@@ -4,6 +4,10 @@ import {ListWrapper} from 'angular2/src/facade/collection';
 import {ChangeDetectorRef} from '../change_detector_ref';
 import {Provider, SkipSelfMetadata, OptionalMetadata, Injectable} from 'angular2/src/core/di';
 
+/**
+ * A strategy for tracking changes over time to an iterable. Used for {@link NgFor} to
+ * respond to changes in an iterable by effecting equivalent changes in the DOM.
+ */
 export interface IterableDiffer {
   diff(object: Object): any;
   onDestroy();
diff --git a/modules/angular2/src/core/change_detection/differs/keyvalue_differs.ts b/modules/angular2/src/core/change_detection/differs/keyvalue_differs.ts
index 3c7d248541..83430ca4eb 100644
--- a/modules/angular2/src/core/change_detection/differs/keyvalue_differs.ts
+++ b/modules/angular2/src/core/change_detection/differs/keyvalue_differs.ts
@@ -4,6 +4,9 @@ import {ListWrapper} from 'angular2/src/facade/collection';
 import {ChangeDetectorRef} from '../change_detector_ref';
 import {Provider, SkipSelfMetadata, OptionalMetadata, Injectable} from 'angular2/src/core/di';
 
+/**
+ * A differ that tracks changes made to an object over time.
+ */
 export interface KeyValueDiffer {
   diff(object: Object);
   onDestroy();
diff --git a/modules/angular2/src/core/debug/debug_element.ts b/modules/angular2/src/core/debug/debug_element.ts
index 2ee97ad2c5..c26acb8188 100644
--- a/modules/angular2/src/core/debug/debug_element.ts
+++ b/modules/angular2/src/core/debug/debug_element.ts
@@ -11,16 +11,28 @@ import {ElementRef, ElementRef_} from 'angular2/src/core/linker/element_ref';
  * 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}.
+ * A DebugElement can be obtained from a {@link ComponentFixture} or from an
+ * {@link ElementRef} via {@link inspectElement}.
  */
 export abstract class DebugElement {
+  /**
+   * Return the instance of the component associated with this element, if any.
+   */
   get componentInstance(): any { return unimplemented(); };
 
+  /**
+   * Return the native HTML element for this DebugElement.
+   */
   get nativeElement(): any { return unimplemented(); };
 
+  /**
+   * Return an Angular {@link ElementRef} for this element.
+   */
   get elementRef(): ElementRef { return unimplemented(); };
 
+  /**
+   * Get the directive active for this element with the given index, if any.
+   */
   abstract getDirectiveInstance(directiveIndex: number): any;
 
   /**
@@ -38,12 +50,26 @@ export abstract class DebugElement {
    */
   get componentViewChildren(): DebugElement[] { return unimplemented(); };
 
+  /**
+   * Simulate an event from this element as if the user had caused
+   * this event to fire from the page.
+   */
   abstract triggerEventHandler(eventName: string, eventObj: Event): void;
 
+  /**
+   * Check whether the element has a directive with the given type.
+   */
   abstract hasDirective(type: Type): boolean;
 
+  /**
+   * Inject the given type from the element injector.
+   */
   abstract inject(type: Type): any;
 
+
+  /**
+   * Read a local variable from the element (e.g. one defined with `#variable`).
+   */
   abstract getLocal(name: string): any;
 
   /**
@@ -169,11 +195,25 @@ export function inspectElement(elementRef: ElementRef): DebugElement {
                            (<ElementRef_>elementRef).boundElementIndex);
 }
 
+/**
+ * Maps an array of {@link DebugElement}s to an array of native DOM elements.
+ */
 export function asNativeElements(arr: DebugElement[]): any[] {
   return arr.map((debugEl) => debugEl.nativeElement);
 }
 
+/**
+ * Set of scope functions used with {@link DebugElement}'s query functionality.
+ */
 export class Scope {
+  /**
+   * Scope queries to both the light dom and view of an element and its
+   * children.
+   *
+   * ## Example
+   *
+   * {@example core/debug/ts/debug_element/debug_element.ts region='scope_all'}
+   */
   static all(debugElement: DebugElement): DebugElement[] {
     var scope = [];
     scope.push(debugElement);
@@ -184,6 +224,14 @@ export class Scope {
 
     return scope;
   }
+
+  /**
+   * Scope queries to the light dom of an element and its children.
+   *
+   * ## Example
+   *
+   * {@example core/debug/ts/debug_element/debug_element.ts region='scope_light'}
+   */
   static light(debugElement: DebugElement): DebugElement[] {
     var scope = [];
     debugElement.children.forEach(child => {
@@ -193,6 +241,13 @@ export class Scope {
     return scope;
   }
 
+  /**
+   * Scope queries to the view of an element of its children.
+   *
+   * ## Example
+   *
+   * {@example core/debug/ts/debug_element/debug_element.ts region='scope_view'}
+   */
   static view(debugElement: DebugElement): DebugElement[] {
     var scope = [];
 
diff --git a/modules/angular2/src/core/di/provider.ts b/modules/angular2/src/core/di/provider.ts
index c60ee1428a..e8c6749568 100644
--- a/modules/angular2/src/core/di/provider.ts
+++ b/modules/angular2/src/core/di/provider.ts
@@ -30,6 +30,10 @@ import {
 } from './exceptions';
 import {resolveForwardRef} from './forward_ref';
 
+/**
+ * `Dependency` is used by the framework to extend DI.
+ * This is internal to Angular and should not be used directly.
+ */
 export class Dependency {
   constructor(public key: Key, public optional: boolean, public lowerBoundVisibility: any,
               public upperBoundVisibility: any, public properties: any[]) {}
@@ -236,6 +240,8 @@ export class Provider {
 }
 
 /**
+ * See {@link Provider} instead.
+ *
  * @deprecated
  */
 @CONST()
@@ -311,6 +317,8 @@ export interface ResolvedProvider {
 }
 
 /**
+ * See {@link ResolvedProvider} instead.
+ *
  * @deprecated
  */
 export interface ResolvedBinding extends ResolvedProvider {}
@@ -339,7 +347,6 @@ export class ResolvedFactory {
 }
 
 /**
- * @deprecated
  * Creates a {@link Provider}.
  *
  * To construct a {@link Provider}, bind a `token` to either a class, a value, a factory function,
@@ -348,6 +355,8 @@ export class ResolvedFactory {
  * See {@link ProviderBuilder} for more details.
  *
  * The `token` is most commonly a class or {@link angular2/di/OpaqueToken}.
+ *
+ * @deprecated
  */
 export function bind(token): ProviderBuilder {
   return new ProviderBuilder(token);
diff --git a/modules/angular2/src/core/linker/component_url_mapper.ts b/modules/angular2/src/core/linker/component_url_mapper.ts
index 97200294ee..b35c3bf618 100644
--- a/modules/angular2/src/core/linker/component_url_mapper.ts
+++ b/modules/angular2/src/core/linker/component_url_mapper.ts
@@ -8,7 +8,7 @@ import {reflector} from 'angular2/src/core/reflection/reflection';
  *
  * This interface can be overridden by the application developer to create custom behavior.
  *
- * See {@link Compiler}
+ * See {@link Compiler}.
  */
 @Injectable()
 export class ComponentUrlMapper {
@@ -23,12 +23,18 @@ export class ComponentUrlMapper {
   }
 }
 
+/**
+ * A {@link ComponentUrlMapper} that maintains an internal map of types to URLs.
+ */
 export class RuntimeComponentUrlMapper extends ComponentUrlMapper {
   /** @internal */
   _componentUrls = new Map<Type, string>();
 
   constructor() { super(); }
 
+  /**
+   * Add a mapping from component type to url to the resolver.
+   */
   setComponentUrl(component: Type, url: string) { this._componentUrls.set(component, url); }
 
   getUrl(component: Type): string {
diff --git a/modules/angular2/src/core/linker/view_ref.ts b/modules/angular2/src/core/linker/view_ref.ts
index adc410162f..7cf3af02ad 100644
--- a/modules/angular2/src/core/linker/view_ref.ts
+++ b/modules/angular2/src/core/linker/view_ref.ts
@@ -40,7 +40,7 @@ export interface HostViewRef {
  *
  * Properties of elements in a View can change, but the structure (number and order) of elements in
  * a View cannot. Changing the structure of Elements can only be done by inserting, moving or
- * removing nested Views via a {@link ViewContainer}. Each View can contain many View Containers.
+ * removing nested Views via a {@link ViewContainerRef}. Each View can contain many View Containers.
  * <!-- /TODO -->
  *
  * ### Example
diff --git a/modules/angular2/src/core/linker/view_resolver.ts b/modules/angular2/src/core/linker/view_resolver.ts
index 49285b8510..35d90d5d3e 100644
--- a/modules/angular2/src/core/linker/view_resolver.ts
+++ b/modules/angular2/src/core/linker/view_resolver.ts
@@ -9,6 +9,9 @@ import {Map} from 'angular2/src/facade/collection';
 import {reflector} from 'angular2/src/core/reflection/reflection';
 
 
+/**
+ * Resolves types to {@link ViewMetadata}.
+ */
 @Injectable()
 export class ViewResolver {
   /** @internal */
diff --git a/modules/angular2/src/core/metadata.ts b/modules/angular2/src/core/metadata.ts
index df3292be0f..fc41837254 100644
--- a/modules/angular2/src/core/metadata.ts
+++ b/modules/angular2/src/core/metadata.ts
@@ -396,21 +396,33 @@ export interface QueryFactory {
   new (selector: Type | string, {descendants}?: {descendants?: boolean}): QueryMetadata;
 }
 
+/**
+ * Factory for {@link ContentChildren}.
+ */
 export interface ContentChildrenFactory {
   (selector: Type | string, {descendants}?: {descendants?: boolean}): any;
   new (selector: Type | string, {descendants}?: {descendants?: boolean}): ContentChildrenMetadata;
 }
 
+/**
+ * Factory for {@link ContentChild}.
+ */
 export interface ContentChildFactory {
   (selector: Type | string): any;
   new (selector: Type | string): ContentChildFactory;
 }
 
+/**
+ * Factory for {@link ViewChildren}.
+ */
 export interface ViewChildrenFactory {
   (selector: Type | string): any;
   new (selector: Type | string): ViewChildrenMetadata;
 }
 
+/**
+ * Factory for {@link ViewChild}.
+ */
 export interface ViewChildFactory {
   (selector: Type | string): any;
   new (selector: Type | string): ViewChildFactory;
diff --git a/modules/angular2/src/core/profile/wtf_impl.ts b/modules/angular2/src/core/profile/wtf_impl.ts
index 133e1a59a5..1a5e5e1074 100644
--- a/modules/angular2/src/core/profile/wtf_impl.ts
+++ b/modules/angular2/src/core/profile/wtf_impl.ts
@@ -1,5 +1,8 @@
 import {global} from 'angular2/src/facade/lang';
 
+/**
+ * A scope function for the Web Tracing Framework (WTF).
+ */
 export interface WtfScopeFn { (arg0?: any, arg1?: any): any; }
 
 interface WTF {
diff --git a/modules/angular2/src/core/reflection/reflection.ts b/modules/angular2/src/core/reflection/reflection.ts
index a22b118771..2d4fc89f74 100644
--- a/modules/angular2/src/core/reflection/reflection.ts
+++ b/modules/angular2/src/core/reflection/reflection.ts
@@ -4,4 +4,8 @@ import {Reflector} from './reflector';
 export {Reflector, ReflectionInfo} from './reflector';
 import {ReflectionCapabilities} from './reflection_capabilities';
 
+/**
+ * The {@link Reflector} used internally in Angular to access metadata
+ * about symbols.
+ */
 export var reflector = new Reflector(new ReflectionCapabilities());
diff --git a/modules/angular2/src/core/reflection/reflector.ts b/modules/angular2/src/core/reflection/reflector.ts
index e19e65e944..5b58109d78 100644
--- a/modules/angular2/src/core/reflection/reflector.ts
+++ b/modules/angular2/src/core/reflection/reflector.ts
@@ -13,11 +13,18 @@ import {PlatformReflectionCapabilities} from './platform_reflection_capabilities
 export {SetterFn, GetterFn, MethodFn} from './types';
 export {PlatformReflectionCapabilities} from './platform_reflection_capabilities';
 
+/**
+ * Reflective information about a symbol, including annotations, interfaces, and other metadata.
+ */
 export class ReflectionInfo {
   constructor(public annotations?: any[], public parameters?: any[][], public factory?: Function,
               public interfaces?: any[], public propMetadata?: {[key: string]: any[]}) {}
 }
 
+/**
+ * Provides access to reflection data about symbols. Used internally by Angular
+ * to power dependency injection and compilation.
+ */
 export class Reflector {
   /** @internal */
   _injectableInfo = new Map<any, ReflectionInfo>();
diff --git a/modules/angular2/src/core/render/api.ts b/modules/angular2/src/core/render/api.ts
index fc2461659b..c5bcc1c02b 100644
--- a/modules/angular2/src/core/render/api.ts
+++ b/modules/angular2/src/core/render/api.ts
@@ -21,9 +21,9 @@ export class RenderProtoViewRef {}
  * Represents a list of sibling Nodes that can be moved by the {@link Renderer} independently of
  * other Render Fragments.
  *
- * Any {@link RenderView} has one Render Fragment.
+ * Any {@link RenderViewRef} has one Render Fragment.
  *
- * Additionally any View with an Embedded View that contains a {@link NgContent View Projection}
+ * Additionally any View with an Embedded View that contains a {@link NgContentAst View Projection}
  * results in additional Render Fragment.
  */
 /*
@@ -71,19 +71,31 @@ export class RenderFragmentRef {}
 // TODO(i): refactor into an interface
 export class RenderViewRef {}
 
+/**
+ * Abstract base class for commands to the Angular renderer, using the visitor pattern.
+ */
 export abstract class RenderTemplateCmd {
   abstract visit(visitor: RenderCommandVisitor, context: any): any;
 }
 
+/**
+ * Command to begin rendering.
+ */
 export abstract class RenderBeginCmd extends RenderTemplateCmd {
   get ngContentIndex(): number { return unimplemented(); };
   get isBound(): boolean { return unimplemented(); };
 }
 
+/**
+ * Command to render text.
+ */
 export abstract class RenderTextCmd extends RenderBeginCmd {
   get value(): string { return unimplemented(); };
 }
 
+/**
+ * Command to render projected content.
+ */
 export abstract class RenderNgContentCmd extends RenderTemplateCmd {
   // The index of this NgContent element
   get index(): number { return unimplemented(); };
@@ -92,21 +104,33 @@ export abstract class RenderNgContentCmd extends RenderTemplateCmd {
   get ngContentIndex(): number { return unimplemented(); };
 }
 
+/**
+ * Command to begin rendering an element.
+ */
 export abstract class RenderBeginElementCmd extends RenderBeginCmd {
   get name(): string { return unimplemented(); };
   get attrNameAndValues(): string[] { return unimplemented(); };
   get eventTargetAndNames(): string[] { return unimplemented(); };
 }
 
+/**
+ * Command to begin rendering a component.
+ */
 export abstract class RenderBeginComponentCmd extends RenderBeginElementCmd {
   get templateId(): string { return unimplemented(); };
 }
 
+/**
+ * Command to render a component's template.
+ */
 export abstract class RenderEmbeddedTemplateCmd extends RenderBeginElementCmd {
   get isMerged(): boolean { return unimplemented(); };
   get children(): RenderTemplateCmd[] { return unimplemented(); };
 }
 
+/**
+ * Visitor for a {@link RenderTemplateCmd}.
+ */
 export interface RenderCommandVisitor {
   visitText(cmd: RenderTextCmd, context: any): any;
   visitNgContent(cmd: RenderNgContentCmd, context: any): any;
@@ -161,6 +185,9 @@ export interface RenderElementRef {
   boundElementIndex: number;
 }
 
+/**
+ * Template for rendering a component, including commands and styles.
+ */
 export class RenderComponentTemplate {
   constructor(public id: string, public shortId: string, public encapsulation: ViewEncapsulation,
               public commands: RenderTemplateCmd[], public styles: string[]) {}
@@ -176,7 +203,7 @@ export class RenderComponentTemplate {
  *
  * If you are implementing a custom renderer, you must implement this interface.
  *
- * The default Renderer implementation is {@link DomRenderer}. Also see {@link WebWorkerRenderer}.
+ * The default Renderer implementation is `DomRenderer`. Also available is `WebWorkerRenderer`.
  */
 export abstract class Renderer {
   /**
diff --git a/modules/angular2/src/core/testability/testability.ts b/modules/angular2/src/core/testability/testability.ts
index 741cffb8e4..ebd9dcd829 100644
--- a/modules/angular2/src/core/testability/testability.ts
+++ b/modules/angular2/src/core/testability/testability.ts
@@ -88,6 +88,9 @@ export class Testability {
   }
 }
 
+/**
+ * A global registry of {@link Testability} instances for specific elements.
+ */
 @Injectable()
 export class TestabilityRegistry {
   /** @internal */
@@ -108,6 +111,10 @@ export class TestabilityRegistry {
   }
 }
 
+/**
+ * Adapter interface for retrieving the `Testability` service associated for a
+ * particular context.
+ */
 export interface GetTestability {
   addToWindow(registry: TestabilityRegistry): void;
   findTestabilityInTree(registry: TestabilityRegistry, elem: any,
@@ -123,6 +130,9 @@ class _NoopGetTestability implements GetTestability {
   }
 }
 
+/**
+ * Set the {@link GetTestability} implementation used by the Angular testing framework.
+ */
 export function setTestabilityGetter(getter: GetTestability): void {
   _testabilityGetter = getter;
 }
diff --git a/modules/angular2/src/core/zone/ng_zone.ts b/modules/angular2/src/core/zone/ng_zone.ts
index 0df53e44a5..b9669f2a41 100644
--- a/modules/angular2/src/core/zone/ng_zone.ts
+++ b/modules/angular2/src/core/zone/ng_zone.ts
@@ -8,8 +8,14 @@ export interface NgZoneZone extends Zone {
   _innerZone: boolean;
 }
 
+/**
+ * Interface for a function with zero arguments.
+ */
 export interface ZeroArgFunction { (): void; }
 
+/**
+ * Function type for an error handler, which takes an error and a stack trace.
+ */
 export interface ErrorHandlingFn { (error: any, stackTrace: any): void; }
 
 /**
diff --git a/modules/angular2/src/facade/collection.ts b/modules/angular2/src/facade/collection.ts
index a35e9391a9..aabbe66f0e 100644
--- a/modules/angular2/src/facade/collection.ts
+++ b/modules/angular2/src/facade/collection.ts
@@ -166,6 +166,10 @@ export class StringMapWrapper {
   }
 }
 
+/**
+ * A boolean-valued function over a value, possibly including context information
+ * regarding that value's position in an array.
+ */
 export interface Predicate<T> { (value: T, index?: number, array?: T[]): boolean; }
 
 export class ListWrapper {
diff --git a/modules/angular2/src/facade/exceptions.ts b/modules/angular2/src/facade/exceptions.ts
index cd8ee4cb52..a5cb614046 100644
--- a/modules/angular2/src/facade/exceptions.ts
+++ b/modules/angular2/src/facade/exceptions.ts
@@ -12,6 +12,9 @@ export class BaseException extends Error {
   toString(): string { return this.message; }
 }
 
+/**
+ * Wraps an exception and provides additional context or information.
+ */
 export class WrappedException extends Error {
   private _wrapperStack: any;
 
diff --git a/modules/angular2/src/facade/lang.ts b/modules/angular2/src/facade/lang.ts
index bd4be8060d..4c0042a984 100644
--- a/modules/angular2/src/facade/lang.ts
+++ b/modules/angular2/src/facade/lang.ts
@@ -29,6 +29,10 @@ export var Type = Function;
  * the `MyCustomComponent` constructor function.
  */
 export interface Type extends Function {}
+
+/**
+ * Runtime representation of a type that is constructable (non-abstract).
+ */
 export interface ConcreteType extends Type { new (...args): any; }
 
 export function getTypeNameForDebugging(type: Type): string {
diff --git a/modules/angular2/src/http/backends/browser_xhr.ts b/modules/angular2/src/http/backends/browser_xhr.ts
index 0665ae7b46..42051915e3 100644
--- a/modules/angular2/src/http/backends/browser_xhr.ts
+++ b/modules/angular2/src/http/backends/browser_xhr.ts
@@ -1,6 +1,10 @@
 import {Injectable} from 'angular2/core';
 
-// Make sure not to evaluate this in a non-browser environment!
+/**
+ * A backend for http that uses the `XMLHttpRequest` browser API.
+ *
+ * Take care not to evaluate this in non-browser contexts.
+ */
 @Injectable()
 export class BrowserXhr {
   constructor() {}
diff --git a/modules/angular2/src/http/backends/jsonp_backend.ts b/modules/angular2/src/http/backends/jsonp_backend.ts
index f0bada51b3..40d4beb8db 100644
--- a/modules/angular2/src/http/backends/jsonp_backend.ts
+++ b/modules/angular2/src/http/backends/jsonp_backend.ts
@@ -12,10 +12,29 @@ import {Observable} from 'rxjs/Observable';
 const JSONP_ERR_NO_CALLBACK = 'JSONP injected script did not invoke callback.';
 const JSONP_ERR_WRONG_METHOD = 'JSONP requests must use GET request method.';
 
+/**
+ * Abstract base class for an in-flight JSONP request.
+ */
 export abstract class JSONPConnection implements Connection {
+  /**
+   * The {@link ReadyState} of this request.
+   */
   readyState: ReadyState;
+
+  /**
+   * The outgoing HTTP request.
+   */
   request: Request;
+
+  /**
+   * An observable that completes with the response, when the request is finished.
+   */
   response: Observable<Response>;
+
+  /**
+   * Callback called when the JSONP request completes, to notify the application
+   * of the new data.
+   */
   abstract finished(data?: any): void;
 }
 
@@ -111,6 +130,9 @@ export class JSONPConnection_ extends JSONPConnection {
   }
 }
 
+/**
+ * A {@link ConnectionBackend} that uses the JSONP strategy of making requests.
+ */
 export abstract class JSONPBackend extends ConnectionBackend {}
 
 @Injectable()
diff --git a/modules/angular2/src/http/http.ts b/modules/angular2/src/http/http.ts
index bdb2a40e35..798b40a333 100644
--- a/modules/angular2/src/http/http.ts
+++ b/modules/angular2/src/http/http.ts
@@ -35,7 +35,7 @@ function mergeOptions(defaultOpts, providedOpts, method, url): RequestOptions {
  * Performs http requests using `XMLHttpRequest` as the default backend.
  *
  * `Http` is available as an injectable class, with methods to perform http requests. Calling
- * `request` returns an {@link Observable} which will emit a single {@link Response} when a
+ * `request` returns an `Observable` which will emit a single {@link Response} when a
  * response is received.
  *
  * ### Example
diff --git a/modules/angular2/src/mock/directive_resolver_mock.ts b/modules/angular2/src/mock/directive_resolver_mock.ts
index b6a6451265..267c664a10 100644
--- a/modules/angular2/src/mock/directive_resolver_mock.ts
+++ b/modules/angular2/src/mock/directive_resolver_mock.ts
@@ -4,6 +4,10 @@ import {Type, isPresent, stringify, isBlank, print} from 'angular2/src/facade/la
 import {DirectiveMetadata, ComponentMetadata} from '../core/metadata';
 import {DirectiveResolver} from 'angular2/src/core/linker/directive_resolver';
 
+/**
+ * An implementation of {@link DirectiveResolver} that allows overriding
+ * various properties of directives.
+ */
 @Injectable()
 export class MockDirectiveResolver extends DirectiveResolver {
   private _providerOverrides = new Map<Type, any[]>();
diff --git a/modules/angular2/src/mock/location_mock.ts b/modules/angular2/src/mock/location_mock.ts
index 551dc8cca7..0c70727e46 100644
--- a/modules/angular2/src/mock/location_mock.ts
+++ b/modules/angular2/src/mock/location_mock.ts
@@ -3,6 +3,9 @@ import {EventEmitter, ObservableWrapper} from 'angular2/src/facade/async';
 import {ListWrapper} from 'angular2/src/facade/collection';
 import {Location} from 'angular2/src/router/location';
 
+/**
+ * A spy for {@link Location} that allows tests to fire simulated location events.
+ */
 @Injectable()
 export class SpyLocation implements Location {
   urlChanges: string[] = [];
diff --git a/modules/angular2/src/mock/mock_application_ref.ts b/modules/angular2/src/mock/mock_application_ref.ts
index 568e5fac29..77062f0f68 100644
--- a/modules/angular2/src/mock/mock_application_ref.ts
+++ b/modules/angular2/src/mock/mock_application_ref.ts
@@ -6,6 +6,9 @@ import {Provider, Injector} from 'angular2/src/core/di';
 import {NgZone} from 'angular2/src/core/zone/ng_zone';
 import {Promise} from 'angular2/src/facade/async';
 
+/**
+ * A no-op implementation of {@link ApplicationRef}, useful for testing.
+ */
 @Injectable()
 export class MockApplicationRef extends ApplicationRef {
   registerBootstrapListener(listener: (ref: ComponentRef) => void): void {}
diff --git a/modules/angular2/src/mock/mock_location_strategy.ts b/modules/angular2/src/mock/mock_location_strategy.ts
index 0bd8f7a746..f15c710106 100644
--- a/modules/angular2/src/mock/mock_location_strategy.ts
+++ b/modules/angular2/src/mock/mock_location_strategy.ts
@@ -3,6 +3,10 @@ import {EventEmitter, ObservableWrapper} from 'angular2/src/facade/async';
 import {LocationStrategy} from 'angular2/src/router/location_strategy';
 
 
+/**
+ * A mock implementation of {@link LocationStrategy} that allows tests to fire simulated
+ * location events.
+ */
 @Injectable()
 export class MockLocationStrategy extends LocationStrategy {
   internalBaseHref: string = '/';
diff --git a/modules/angular2/src/mock/ng_zone_mock.ts b/modules/angular2/src/mock/ng_zone_mock.ts
index 20f20dfdbe..443db975f6 100644
--- a/modules/angular2/src/mock/ng_zone_mock.ts
+++ b/modules/angular2/src/mock/ng_zone_mock.ts
@@ -2,6 +2,9 @@ import {Injectable} from 'angular2/src/core/di';
 import {NgZone} from 'angular2/src/core/zone/ng_zone';
 import {EventEmitter, ObservableWrapper} from 'angular2/src/facade/async';
 
+/**
+ * A mock implementation of {@link NgZone}.
+ */
 @Injectable()
 export class MockNgZone extends NgZone {
   /** @internal */
diff --git a/modules/angular2/src/platform/browser/browser_adapter.ts b/modules/angular2/src/platform/browser/browser_adapter.ts
index 986c90e2ec..d01b723923 100644
--- a/modules/angular2/src/platform/browser/browser_adapter.ts
+++ b/modules/angular2/src/platform/browser/browser_adapter.ts
@@ -53,6 +53,9 @@ var _chromeNumKeyPadMap = {
   '\x90': 'NumLock'
 };
 
+/**
+ * A `DomAdapter` powered by full browser DOM APIs.
+ */
 /* tslint:disable:requireParameterType */
 export class BrowserDomAdapter extends GenericBrowserDomAdapter {
   parse(templateHtml: string) { throw new Error("parse not implemented"); }
diff --git a/modules/angular2/src/platform/browser_common.ts b/modules/angular2/src/platform/browser_common.ts
index 300829bffc..d99a2d756a 100644
--- a/modules/angular2/src/platform/browser_common.ts
+++ b/modules/angular2/src/platform/browser_common.ts
@@ -42,6 +42,11 @@ export {
 export {BrowserDomAdapter} from './browser/browser_adapter';
 export {enableDebugTools, disableDebugTools} from 'angular2/src/platform/browser/tools/tools';
 
+/**
+ * A set of providers to initialize the Angular platform in a web browser.
+ *
+ * Used automatically by `bootstrap`, or can be passed to {@link platform}.
+ */
 export const BROWSER_PROVIDERS: Array<any /*Type | Provider | any[]*/> = CONST_EXPR([
   PLATFORM_COMMON_PROVIDERS,
   new Provider(PLATFORM_INITIALIZER, {useValue: initDomAdapter, multi: true}),
@@ -57,6 +62,11 @@ function _document(): any {
   return DOM.defaultDoc();
 }
 
+/**
+ * A set of providers to initialize an Angular application in a web browser.
+ *
+ * Used automatically by `bootstrap`, or can be passed to {@link PlatformRef.application}.
+ */
 export const BROWSER_APP_COMMON_PROVIDERS: Array<any /*Type | Provider | any[]*/> = CONST_EXPR([
   APPLICATION_COMMON_PROVIDERS,
   FORM_PROVIDERS,
diff --git a/modules/angular2/src/platform/dom/debug/by.ts b/modules/angular2/src/platform/dom/debug/by.ts
index 9daa684f42..b3933f50a8 100644
--- a/modules/angular2/src/platform/dom/debug/by.ts
+++ b/modules/angular2/src/platform/dom/debug/by.ts
@@ -3,9 +3,26 @@ import {Predicate} from 'angular2/src/facade/collection';
 import {DOM} from 'angular2/src/platform/dom/dom_adapter';
 import {DebugElement} from 'angular2/core';
 
+/**
+ * Predicates for use with {@link DebugElement}'s query functions.
+ */
 export class By {
-  static all(): Function { return (debugElement) => true; }
+  /**
+   * Match all elements.
+   *
+   * ## Example
+   *
+   * {@example platform/dom/debug/ts/by/by.ts region='by_all'}
+   */
+  static all(): Predicate<DebugElement> { return (debugElement) => true; }
 
+  /**
+   * Match elements by the given CSS selector.
+   *
+   * ## Example
+   *
+   * {@example platform/dom/debug/ts/by/by.ts region='by_css'}
+   */
   static css(selector: string): Predicate<DebugElement> {
     return (debugElement) => {
       return isPresent(debugElement.nativeElement) ?
@@ -13,6 +30,14 @@ export class By {
                  false;
     };
   }
+
+  /**
+   * Match elements that have the given directive present.
+   *
+   * ## Example
+   *
+   * {@example platform/dom/debug/ts/by/by.ts region='by_directive'}
+   */
   static directive(type: Type): Predicate<DebugElement> {
     return (debugElement) => { return debugElement.hasDirective(type); };
   }
diff --git a/modules/angular2/src/platform/dom/debug/debug_element_view_listener.ts b/modules/angular2/src/platform/dom/debug/debug_element_view_listener.ts
index 9a023e6ef5..561e817a5d 100644
--- a/modules/angular2/src/platform/dom/debug/debug_element_view_listener.ts
+++ b/modules/angular2/src/platform/dom/debug/debug_element_view_listener.ts
@@ -72,9 +72,21 @@ export class DebugElementViewListener implements AppViewListener {
   }
 }
 
+/**
+ * Providers which support debugging Angular applications (e.g. via `ng.probe`).
+ *
+ * ## Example
+ *
+ * {@example platform/dom/debug/ts/debug_element_view_listener/providers.ts region='providers'}
+ */
 export const ELEMENT_PROBE_PROVIDERS: any[] = CONST_EXPR([
   DebugElementViewListener,
   CONST_EXPR(new Provider(AppViewListener, {useExisting: DebugElementViewListener})),
 ]);
 
+/**
+ * Use {@link ELEMENT_PROBE_PROVIDERS}.
+ *
+ * @deprecated
+ */
 export const ELEMENT_PROBE_BINDINGS = ELEMENT_PROBE_PROVIDERS;
diff --git a/modules/angular2/src/router/route_config_decorator.ts b/modules/angular2/src/router/route_config_decorator.ts
index bfac76e4b8..bb0e1535fb 100644
--- a/modules/angular2/src/router/route_config_decorator.ts
+++ b/modules/angular2/src/router/route_config_decorator.ts
@@ -2,5 +2,12 @@ import {RouteConfig as RouteConfigAnnotation, RouteDefinition} from './route_con
 import {makeDecorator} from 'angular2/src/core/util/decorators';
 
 export {Route, Redirect, AuxRoute, AsyncRoute, RouteDefinition} from './route_config_impl';
+
+// Copied from RouteConfig in route_config_impl.
+/**
+ * The `RouteConfig` decorator defines routes for a given component.
+ *
+ * It takes an array of {@link RouteDefinition}s.
+ */
 export var RouteConfig: (configs: RouteDefinition[]) => ClassDecorator =
     makeDecorator(RouteConfigAnnotation);
diff --git a/modules/angular2/src/router/route_definition.ts b/modules/angular2/src/router/route_definition.ts
index 7d38690ee1..c34c278158 100644
--- a/modules/angular2/src/router/route_definition.ts
+++ b/modules/angular2/src/router/route_definition.ts
@@ -23,6 +23,12 @@ export interface RouteDefinition {
   useAsDefault?: boolean;
 }
 
+/**
+ * Represents either a component type (`type` is `component`) or a loader function
+ * (`type` is `loader`).
+ *
+ * See also {@link RouteDefinition}.
+ */
 export interface ComponentDefinition {
   type: string;
   loader?: Function;
diff --git a/modules/angular2/src/testing/fake_async.ts b/modules/angular2/src/testing/fake_async.ts
index 832ed5f1d4..49cc35dc54 100644
--- a/modules/angular2/src/testing/fake_async.ts
+++ b/modules/angular2/src/testing/fake_async.ts
@@ -19,6 +19,10 @@ interface FakeAsyncZone extends NgZoneZone {
  *
  * If there are any pending timers at the end of the function, an exception will be thrown.
  *
+ * ## Example
+ *
+ * {@example testing/ts/fake_async.ts region='basic'}
+ *
  * @param fn
  * @returns {Function} The function wrapped to be executed in the fakeAsync zone
  */
@@ -63,8 +67,17 @@ export function fakeAsync(fn: Function): Function {
   }
 }
 
-// TODO we should fix tick to dequeue the failed timer instead of relying on clearPendingTimers
+/**
+ * Clear the queue of pending timers and microtasks.
+ *
+ * Useful for cleaning up after an asynchronous test passes.
+ *
+ * ## Example
+ *
+ * {@example testing/ts/fake_async.ts region='pending'}
+ */
 export function clearPendingTimers(): void {
+  // TODO we should fix tick to dequeue the failed timer instead of relying on clearPendingTimers
   ListWrapper.clear(_microtasks);
   ListWrapper.clear(_pendingPeriodicTimers);
   ListWrapper.clear(_pendingTimers);
@@ -77,6 +90,10 @@ export function clearPendingTimers(): void {
  * The microtasks queue is drained at the very start of this function and after any timer callback
  * has been executed.
  *
+ * ## Example
+ *
+ * {@example testing/ts/fake_async.ts region='basic'}
+ *
  * @param {number} millis Number of millisecond, defaults to 0
  */
 export function tick(millis: number = 0): void {
diff --git a/modules/angular2/src/testing/matchers.ts b/modules/angular2/src/testing/matchers.ts
index 163b68e92c..79e21f7236 100644
--- a/modules/angular2/src/testing/matchers.ts
+++ b/modules/angular2/src/testing/matchers.ts
@@ -2,21 +2,97 @@ import {DOM} from 'angular2/src/platform/dom/dom_adapter';
 import {global, isString} from 'angular2/src/facade/lang';
 import {StringMapWrapper} from 'angular2/src/facade/collection';
 
-
+/**
+ * Jasmine matchers that check Angular specific conditions.
+ */
 export interface NgMatchers extends jasmine.Matchers {
+  /**
+   * Expect the value to be a `Promise`.
+   *
+   * ## Example
+   *
+   * {@example testing/ts/matchers.ts region='toBePromise'}
+   */
   toBePromise(): boolean;
+
+  /**
+   * Expect the value to be an instance of a class.
+   *
+   * ## Example
+   *
+   * {@example testing/ts/matchers.ts region='toBeAnInstanceOf'}
+   */
   toBeAnInstanceOf(expected: any): boolean;
+
+  /**
+   * Expect the element to have exactly the given text.
+   *
+   * ## Example
+   *
+   * {@example testing/ts/matchers.ts region='toHaveText'}
+   */
   toHaveText(expected: any): boolean;
+
+  /**
+   * Expect the element to have the given CSS class.
+   *
+   * ## Example
+   *
+   * {@example testing/ts/matchers.ts region='toHaveCssClass'}
+   */
   toHaveCssClass(expected: any): boolean;
+
+  /**
+   * Expect the element to have the given CSS styles.
+   *
+   * ## Example
+   *
+   * {@example testing/ts/matchers.ts region='toHaveCssStyle'}
+   */
   toHaveCssStyle(expected: any): boolean;
+
+  /**
+   * Expect a class to implement the interface of the given class.
+   *
+   * ## Example
+   *
+   * {@example testing/ts/matchers.ts region='toImplement'}
+   */
   toImplement(expected: any): boolean;
+
+  /**
+   * Expect an exception to contain the given error text.
+   *
+   * ## Example
+   *
+   * {@example testing/ts/matchers.ts region='toContainError'}
+   */
   toContainError(expected: any): boolean;
+
+  /**
+   * Expect a function to throw an error with the given error text when executed.
+   *
+   * ## Example
+   *
+   * {@example testing/ts/matchers.ts region='toThrowErrorWith'}
+   */
   toThrowErrorWith(expectedMessage: any): boolean;
+
+  /**
+   * Invert the matchers.
+   */
   not: NgMatchers;
 }
 
 var _global: jasmine.GlobalPolluter = <any>(typeof window === 'undefined' ? global : window);
 
+/**
+ * Jasmine matching function with Angular matchers mixed in.
+ *
+ * ## Example
+ *
+ * {@example testing/ts/matchers.ts region='toHaveText'}
+ */
 export var expect: (actual: any) => NgMatchers = <any>_global.expect;
 
 
diff --git a/modules/angular2/src/testing/test_injector.ts b/modules/angular2/src/testing/test_injector.ts
index ff7880adbf..1fac9583c7 100644
--- a/modules/angular2/src/testing/test_injector.ts
+++ b/modules/angular2/src/testing/test_injector.ts
@@ -131,6 +131,9 @@ function _runtimeCompilerBindings() {
   ];
 }
 
+/**
+ * Configures an injector suitable for testing.
+ */
 export class TestInjector {
   private _instantiated: boolean = false;
 
@@ -169,6 +172,10 @@ export class TestInjector {
 
 var _testInjector: TestInjector = null;
 
+/**
+ * Retrieve the {@link TestInjector}, possibly creating one if it doesn't
+ * exist yet.
+ */
 export function getTestInjector() {
   if (_testInjector == null) {
     _testInjector = new TestInjector();
@@ -209,12 +216,17 @@ export function inject(tokens: any[], fn: Function): FunctionWithParamTokens {
 }
 
 /**
- * @deprecated Use inject instead, which now supports both synchronous and asynchronous tests.
+ * Use {@link inject} instead, which now supports both synchronous and asynchronous tests.
+ *
+ * @deprecated
  */
 export function injectAsync(tokens: any[], fn: Function): FunctionWithParamTokens {
   return new FunctionWithParamTokens(tokens, fn, true);
 }
 
+/**
+ * A testing function with parameters which will be injected. See {@link inject} for details.
+ */
 export class FunctionWithParamTokens {
   constructor(private _tokens: any[], private _fn: Function, public isAsync: boolean) {}
 
diff --git a/modules/angular2/src/testing/testing.ts b/modules/angular2/src/testing/testing.ts
index a72c450625..875016029f 100644
--- a/modules/angular2/src/testing/testing.ts
+++ b/modules/angular2/src/testing/testing.ts
@@ -72,8 +72,20 @@ export var fdescribe: Function = _global.fdescribe;
  */
 export var xdescribe: Function = _global.xdescribe;
 
+/**
+ * Signature for a synchronous test function (no arguments).
+ */
 export type SyncTestFn = () => void;
+
+/**
+ * Signature for an asynchronous test function which takes a
+ * `done` callback.
+ */
 export type AsyncTestFn = (done: () => void) => void;
+
+/**
+ * Signature for any simple testing function.
+ */
 export type AnyTestFn = SyncTestFn | AsyncTestFn;
 
 var jsmBeforeEach = _global.beforeEach;
@@ -226,7 +238,7 @@ export function beforeEach(fn: FunctionWithParamTokens | AnyTestFn): void {
  *
  * ## Example:
  *
- * {@example testing/ts/testing.ts region='it'}
+ * {@example testing/ts/testing.ts region='describeIt'}
  */
 export function it(name: string, fn: FunctionWithParamTokens | AnyTestFn,
                    timeOut: number = null): void {
diff --git a/modules/angular2/src/testing/testing_internal.ts b/modules/angular2/src/testing/testing_internal.ts
index 2dfebc146f..72ca9ebb10 100644
--- a/modules/angular2/src/testing/testing_internal.ts
+++ b/modules/angular2/src/testing/testing_internal.ts
@@ -22,6 +22,9 @@ export type SyncTestFn = () => void;
 type AsyncTestFn = (done: () => void) => void;
 type AnyTestFn = SyncTestFn | AsyncTestFn;
 
+/**
+ * Injectable completer that allows signaling completion of an asynchronous test. Used internally.
+ */
 export class AsyncTestCompleter {
   constructor(private _done: Function) {}