docs(*): Document a lot more symbols that are missing comments in our generated docs.

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

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

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

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

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

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

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

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;

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;

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;

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"));

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: {

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]

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;

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
  *

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,

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,

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,

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();

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[][]) {}
 }

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 = [];

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>();

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 {

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]) || "";

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; }
 }

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;
 

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; }
 }
 

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;
 

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,

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();