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

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 {

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;
 
 

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

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 {

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