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

modules/angular2/src/testing/testing.ts

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