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

modules/angular2/src/core/application_ref.ts

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

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

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

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

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

modules/angular2/src/core/metadata.ts

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

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

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

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

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