From 947bf11cb69a2c81bbdb53b1457cd11476b18ee5 Mon Sep 17 00:00:00 2001
From: Alex Eagle <alexeagle@google.com>
Date: Mon, 12 Oct 2015 10:12:11 -0700
Subject: [PATCH] chore(docs): copy [Decorator]Metadata docs to the [Decorator]

This allows editors to show the docs when users navigate to definition.

See #4668

Closes #4683
---
 modules/angular2/src/core/metadata.ts | 867 +++++++++++++++++++++++++-
 1 file changed, 850 insertions(+), 17 deletions(-)

diff --git a/modules/angular2/src/core/metadata.ts b/modules/angular2/src/core/metadata.ts
index 9458f62c52..dae5f067cd 100644
--- a/modules/angular2/src/core/metadata.ts
+++ b/modules/angular2/src/core/metadata.ts
@@ -505,82 +505,915 @@ export interface HostListenerFactory {
   new (eventName: string, args?: string[]): any;
 }
 
+// TODO(alexeagle): remove the duplication of this doc. It is copied from ComponentMetadata.
 /**
- * {@link ComponentMetadata} factory function.
+ * Declare reusable UI building blocks for an application.
+ *
+ * Each Angular component requires a single `@Component` and at least one `@View` annotation. The
+ * `@Component`
+ * annotation specifies when a component is instantiated, and which properties and hostListeners it
+ * binds to.
+ *
+ * When a component is instantiated, Angular
+ * - creates a shadow DOM for the component.
+ * - loads the selected template into the shadow DOM.
+ * - creates all the injectable objects configured with `providers` and `viewProviders`.
+ *
+ * All template expressions and statements are then evaluated against the component instance.
+ *
+ * For details on the `@View` annotation, see {@link ViewMetadata}.
+ *
+ * ## Lifecycle hooks
+ *
+ * When the component class implements some {@link angular2/lifecycle_hooks} the callbacks are
+ * called by the change detection at defined points in time during the life of the component.
+ *
+ * ## Example
+ *
+ * ```
+ * @Component({
+ *   selector: 'greet',
+ *   template: 'Hello {{name}}!'
+ * })
+ * class Greet {
+ *   name: string;
+ *
+ *   constructor() {
+ *     this.name = 'World';
+ *   }
+ * }
+ * ```
+ *
  */
 export var Component: ComponentFactory =
     <ComponentFactory>makeDecorator(ComponentMetadata, (fn: any) => fn.View = View);
+
+// TODO(alexeagle): remove the duplication of this doc. It is copied from DirectiveMetadata.
 /**
- * {@link DirectiveMetadata} factory function.
+ * Directives allow you to attach behavior to elements in the DOM.
+ *
+ * {@link DirectiveMetadata}s with an embedded view are called {@link ComponentMetadata}s.
+ *
+ * A directive consists of a single directive annotation and a controller class. When the
+ * directive's `selector` matches
+ * elements in the DOM, the following steps occur:
+ *
+ * 1. For each directive, the `ElementInjector` attempts to resolve the directive's constructor
+ * arguments.
+ * 2. Angular instantiates directives for each matched element using `ElementInjector` in a
+ * depth-first order,
+ *    as declared in the HTML.
+ *
+ * ## Understanding How Injection Works
+ *
+ * There are three stages of injection resolution.
+ * - *Pre-existing Injectors*:
+ *   - The terminal {@link Injector} cannot resolve dependencies. It either throws an error or, if
+ * the dependency was
+ *     specified as `@Optional`, returns `null`.
+ *   - The platform injector resolves browser singleton resources, such as: cookies, title,
+ * location, and others.
+ * - *Component Injectors*: Each component instance has its own {@link Injector}, and they follow
+ * the same parent-child hierarchy
+ *     as the component instances in the DOM.
+ * - *Element Injectors*: Each component instance has a Shadow DOM. Within the Shadow DOM each
+ * element has an `ElementInjector`
+ *     which follow the same parent-child hierarchy as the DOM elements themselves.
+ *
+ * When a template is instantiated, it also must instantiate the corresponding directives in a
+ * depth-first order. The
+ * current `ElementInjector` resolves the constructor dependencies for each directive.
+ *
+ * Angular then resolves dependencies as follows, according to the order in which they appear in the
+ * {@link ViewMetadata}:
+ *
+ * 1. Dependencies on the current element
+ * 2. Dependencies on element injectors and their parents until it encounters a Shadow DOM boundary
+ * 3. Dependencies on component injectors and their parents until it encounters the root component
+ * 4. Dependencies on pre-existing injectors
+ *
+ *
+ * The `ElementInjector` can inject other directives, element-specific special objects, or it can
+ * delegate to the parent
+ * injector.
+ *
+ * To inject other directives, declare the constructor parameter as:
+ * - `directive:DirectiveType`: a directive on the current element only
+ * - `@Host() directive:DirectiveType`: any directive that matches the type between the current
+ * element and the
+ *    Shadow DOM root.
+ * - `@Query(DirectiveType) query:QueryList<DirectiveType>`: A live collection of direct child
+ * directives.
+ * - `@QueryDescendants(DirectiveType) query:QueryList<DirectiveType>`: A live collection of any
+ * child directives.
+ *
+ * To inject element-specific special objects, declare the constructor parameter as:
+ * - `element: ElementRef` to obtain a reference to logical element in the view.
+ * - `viewContainer: ViewContainerRef` to control child template instantiation, for
+ * {@link DirectiveMetadata} directives only
+ * - `bindingPropagation: BindingPropagation` to control change detection in a more granular way.
+ *
+ * ## Example
+ *
+ * The following example demonstrates how dependency injection resolves constructor arguments in
+ * practice.
+ *
+ *
+ * Assume this HTML template:
+ *
+ * ```
+ * <div dependency="1">
+ *   <div dependency="2">
+ *     <div dependency="3" my-directive>
+ *       <div dependency="4">
+ *         <div dependency="5"></div>
+ *       </div>
+ *       <div dependency="6"></div>
+ *     </div>
+ *   </div>
+ * </div>
+ * ```
+ *
+ * With the following `dependency` decorator and `SomeService` injectable class.
+ *
+ * ```
+ * @Injectable()
+ * class SomeService {
+ * }
+ *
+ * @Directive({
+ *   selector: '[dependency]',
+ *   inputs: [
+ *     'id: dependency'
+ *   ]
+ * })
+ * class Dependency {
+ *   id:string;
+ * }
+ * ```
+ *
+ * Let's step through the different ways in which `MyDirective` could be declared...
+ *
+ *
+ * ### No injection
+ *
+ * Here the constructor is declared with no arguments, therefore nothing is injected into
+ * `MyDirective`.
+ *
+ * ```
+ * @Directive({ selector: '[my-directive]' })
+ * class MyDirective {
+ *   constructor() {
+ *   }
+ * }
+ * ```
+ *
+ * This directive would be instantiated with no dependencies.
+ *
+ *
+ * ### Component-level injection
+ *
+ * Directives can inject any injectable instance from the closest component injector or any of its
+ * parents.
+ *
+ * Here, the constructor declares a parameter, `someService`, and injects the `SomeService` type
+ * from the parent
+ * component's injector.
+ * ```
+ * @Directive({ selector: '[my-directive]' })
+ * class MyDirective {
+ *   constructor(someService: SomeService) {
+ *   }
+ * }
+ * ```
+ *
+ * This directive would be instantiated with a dependency on `SomeService`.
+ *
+ *
+ * ### Injecting a directive from the current element
+ *
+ * Directives can inject other directives declared on the current element.
+ *
+ * ```
+ * @Directive({ selector: '[my-directive]' })
+ * class MyDirective {
+ *   constructor(dependency: Dependency) {
+ *     expect(dependency.id).toEqual(3);
+ *   }
+ * }
+ * ```
+ * This directive would be instantiated with `Dependency` declared at the same element, in this case
+ * `dependency="3"`.
+ *
+ * ### Injecting a directive from any ancestor elements
+ *
+ * Directives can inject other directives declared on any ancestor element (in the current Shadow
+ * DOM), i.e. on the current element, the
+ * parent element, or its parents.
+ * ```
+ * @Directive({ selector: '[my-directive]' })
+ * class MyDirective {
+ *   constructor(@Host() dependency: Dependency) {
+ *     expect(dependency.id).toEqual(2);
+ *   }
+ * }
+ * ```
+ *
+ * `@Host` checks the current element, the parent, as well as its parents recursively. If
+ * `dependency="2"` didn't
+ * exist on the direct parent, this injection would
+ * have returned
+ * `dependency="1"`.
+ *
+ *
+ * ### Injecting a live collection of direct child directives
+ *
+ *
+ * A directive can also query for other child directives. Since parent directives are instantiated
+ * before child directives, a directive can't simply inject the list of child directives. Instead,
+ * the directive injects a {@link QueryList}, which updates its contents as children are added,
+ * removed, or moved by a directive that uses a {@link ViewContainerRef} such as a `ng-for`, an
+ * `ng-if`, or an `ng-switch`.
+ *
+ * ```
+ * @Directive({ selector: '[my-directive]' })
+ * class MyDirective {
+ *   constructor(@Query(Dependency) dependencies:QueryList<Dependency>) {
+ *   }
+ * }
+ * ```
+ *
+ * This directive would be instantiated with a {@link QueryList} which contains `Dependency` 4 and
+ * 6. Here, `Dependency` 5 would not be included, because it is not a direct child.
+ *
+ * ### Injecting a live collection of descendant directives
+ *
+ * By passing the descendant flag to `@Query` above, we can include the children of the child
+ * elements.
+ *
+ * ```
+ * @Directive({ selector: '[my-directive]' })
+ * class MyDirective {
+ *   constructor(@Query(Dependency, {descendants: true}) dependencies:QueryList<Dependency>) {
+ *   }
+ * }
+ * ```
+ *
+ * This directive would be instantiated with a Query which would contain `Dependency` 4, 5 and 6.
+ *
+ * ### Optional injection
+ *
+ * The normal behavior of directives is to return an error when a specified dependency cannot be
+ * resolved. If you
+ * would like to inject `null` on unresolved dependency instead, you can annotate that dependency
+ * with `@Optional()`.
+ * This explicitly permits the author of a template to treat some of the surrounding directives as
+ * optional.
+ *
+ * ```
+ * @Directive({ selector: '[my-directive]' })
+ * class MyDirective {
+ *   constructor(@Optional() dependency:Dependency) {
+ *   }
+ * }
+ * ```
+ *
+ * This directive would be instantiated with a `Dependency` directive found on the current element.
+ * If none can be
+ * found, the injector supplies `null` instead of throwing an error.
+ *
+ * ## Example
+ *
+ * Here we use a decorator directive to simply define basic tool-tip behavior.
+ *
+ * ```
+ * @Directive({
+ *   selector: '[tooltip]',
+ *   inputs: [
+ *     'text: tooltip'
+ *   ],
+ *   host: {
+ *     '(mouseenter)': 'onMouseEnter()',
+ *     '(mouseleave)': 'onMouseLeave()'
+ *   }
+ * })
+ * class Tooltip{
+ *   text:string;
+ *   overlay:Overlay; // NOT YET IMPLEMENTED
+ *   overlayManager:OverlayManager; // NOT YET IMPLEMENTED
+ *
+ *   constructor(overlayManager:OverlayManager) {
+ *     this.overlay = overlay;
+ *   }
+ *
+ *   onMouseEnter() {
+ *     // exact signature to be determined
+ *     this.overlay = this.overlayManager.open(text, ...);
+ *   }
+ *
+ *   onMouseLeave() {
+ *     this.overlay.close();
+ *     this.overlay = null;
+ *   }
+ * }
+ * ```
+ * In our HTML template, we can then add this behavior to a `<div>` or any other element with the
+ * `tooltip` selector,
+ * like so:
+ *
+ * ```
+ * <div tooltip="some text here"></div>
+ * ```
+ *
+ * Directives can also control the instantiation, destruction, and positioning of inline template
+ * elements:
+ *
+ * A directive uses a {@link ViewContainerRef} to instantiate, insert, move, and destroy views at
+ * runtime.
+ * The {@link ViewContainerRef} is created as a result of `<template>` element, and represents a
+ * location in the current view
+ * where these actions are performed.
+ *
+ * Views are always created as children of the current {@link ViewMetadata}, and as siblings of the
+ * `<template>` element. Thus a
+ * directive in a child view cannot inject the directive that created it.
+ *
+ * Since directives that create views via ViewContainers are common in Angular, and using the full
+ * `<template>` element syntax is wordy, Angular
+ * also supports a shorthand notation: `<li *foo="bar">` and `<li template="foo: bar">` are
+ * equivalent.
+ *
+ * Thus,
+ *
+ * ```
+ * <ul>
+ *   <li *foo="bar" title="text"></li>
+ * </ul>
+ * ```
+ *
+ * Expands in use to:
+ *
+ * ```
+ * <ul>
+ *   <template [foo]="bar">
+ *     <li title="text"></li>
+ *   </template>
+ * </ul>
+ * ```
+ *
+ * Notice that although the shorthand places `*foo="bar"` within the `<li>` element, the binding for
+ * the directive
+ * controller is correctly instantiated on the `<template>` element rather than the `<li>` element.
+ *
+ * ## Lifecycle hooks
+ *
+ * When the directive class implements some {@link angular2/lifecycle_hooks} the callbacks are
+ * called by the change detection at defined points in time during the life of the directive.
+ *
+ * ## Example
+ *
+ * Let's suppose we want to implement the `unless` behavior, to conditionally include a template.
+ *
+ * Here is a simple directive that triggers on an `unless` selector:
+ *
+ * ```
+ * @Directive({
+ *   selector: '[unless]',
+ *   inputs: ['unless']
+ * })
+ * export class Unless {
+ *   viewContainer: ViewContainerRef;
+ *   templateRef: TemplateRef;
+ *   prevCondition: boolean;
+ *
+ *   constructor(viewContainer: ViewContainerRef, templateRef: TemplateRef) {
+ *     this.viewContainer = viewContainer;
+ *     this.templateRef = templateRef;
+ *     this.prevCondition = null;
+ *   }
+ *
+ *   set unless(newCondition) {
+ *     if (newCondition && (isBlank(this.prevCondition) || !this.prevCondition)) {
+ *       this.prevCondition = true;
+ *       this.viewContainer.clear();
+ *     } else if (!newCondition && (isBlank(this.prevCondition) || this.prevCondition)) {
+ *       this.prevCondition = false;
+ *       this.viewContainer.create(this.templateRef);
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * We can then use this `unless` selector in a template:
+ * ```
+ * <ul>
+ *   <li *unless="expr"></li>
+ * </ul>
+ * ```
+ *
+ * Once the directive instantiates the child view, the shorthand notation for the template expands
+ * and the result is:
+ *
+ * ```
+ * <ul>
+ *   <template [unless]="exp">
+ *     <li></li>
+ *   </template>
+ *   <li></li>
+ * </ul>
+ * ```
+ *
+ * Note also that although the `<li></li>` template still exists inside the `<template></template>`,
+ * the instantiated
+ * view occurs on the second `<li></li>` which is a sibling to the `<template>` element.
  */
 export var Directive: DirectiveFactory = <DirectiveFactory>makeDecorator(DirectiveMetadata);
 
+// TODO(alexeagle): remove the duplication of this doc. It is copied from ViewMetadata.
 /**
- * {@link ViewMetadata} factory function.
+ * Metadata properties available for configuring Views.
+ *
+ * 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}.
+ *
+ * ## Example
+ *
+ * ```
+ * @Component({
+ *   selector: 'greet',
+ *   template: 'Hello {{name}}!',
+ *   directives: [GreetUser, Bold]
+ * })
+ * class Greet {
+ *   name: string;
+ *
+ *   constructor() {
+ *     this.name = 'World';
+ *   }
+ * }
+ * ```
  */
 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.
 /**
- * {@link AttributeMetadata} factory function.
+ * Metadata properties available for configuring Views.
+ *
+ * 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}.
+ *
+ * ## Example
+ *
+ * ```
+ * @Component({
+ *   selector: 'greet',
+ *   template: 'Hello {{name}}!',
+ *   directives: [GreetUser, Bold]
+ * })
+ * class Greet {
+ *   name: string;
+ *
+ *   constructor() {
+ *     this.name = 'World';
+ *   }
+ * }
+ * ```
  */
 export var Attribute: AttributeFactory = makeParamDecorator(AttributeMetadata);
 
+// TODO(alexeagle): remove the duplication of this doc. It is copied from QueryMetadata.
 /**
- * {@link QueryMetadata} factory function.
+ * Declares an injectable parameter to be a live list of directives or variable
+ * bindings from the content children of a directive.
+ *
+ * ### Example ([live demo](http://plnkr.co/edit/lY9m8HLy7z06vDoUaSN2?p=preview))
+ *
+ * Assume that `<tabs>` component would like to get a list its children `<pane>`
+ * components as shown in this example:
+ *
+ * ```html
+ * <tabs>
+ *   <pane title="Overview">...</pane>
+ *   <pane *ng-for="#o of objects" [title]="o.title">{{o.text}}</pane>
+ * </tabs>
+ * ```
+ *
+ * The preferred solution is to query for `Pane` directives using this decorator.
+ *
+ * ```javascript
+ * @Component({
+ *   selector: 'pane',
+ *   inputs: ['title']
+ * })
+ * class Pane {
+ *   title:string;
+ * }
+ *
+ * @Component({
+ *  selector: 'tabs',
+ *  template: `
+ *    <ul>
+ *      <li *ng-for="#pane of panes">{{pane.title}}</li>
+ *    </ul>
+ *    <content></content>
+ *  `
+ * })
+ * class Tabs {
+ *   panes: QueryList<Pane>;
+ *   constructor(@Query(Pane) panes:QueryList<Pane>) {
+ *     this.panes = panes;
+ *   }
+ * }
+ * ```
+ *
+ * A query can look for variable bindings by passing in a string with desired binding symbol.
+ *
+ * ### Example ([live demo](http://plnkr.co/edit/sT2j25cH1dURAyBRCKx1?p=preview))
+ * ```html
+ * <seeker>
+ *   <div #findme>...</div>
+ * </seeker>
+ *
+ * @Component({ selector: 'foo' })
+ * class seeker {
+ *   constructor(@Query('findme') elList: QueryList<ElementRef>) {...}
+ * }
+ * ```
+ *
+ * In this case the object that is injected depend on the type of the variable
+ * binding. It can be an ElementRef, a directive or a component.
+ *
+ * Passing in a comma separated list of variable bindings will query for all of them.
+ *
+ * ```html
+ * <seeker>
+ *   <div #find-me>...</div>
+ *   <div #find-me-too>...</div>
+ * </seeker>
+ *
+ *  @Component({
+ *   selector: 'foo'
+ * })
+ * class Seeker {
+ *   constructor(@Query('findMe, findMeToo') elList: QueryList<ElementRef>) {...}
+ * }
+ * ```
+ *
+ * Configure whether query looks for direct children or all descendants
+ * of the querying element, by using the `descendants` parameter.
+ * It is set to `false` by default.
+ *
+ * ### Example ([live demo](http://plnkr.co/edit/wtGeB977bv7qvA5FTYl9?p=preview))
+ * ```html
+ * <container #first>
+ *   <item>a</item>
+ *   <item>b</item>
+ *   <container #second>
+ *     <item>c</item>
+ *   </container>
+ * </container>
+ * ```
+ *
+ * When querying for items, the first container will see only `a` and `b` by default,
+ * but with `Query(TextDirective, {descendants: true})` it will see `c` too.
+ *
+ * The queried directives are kept in a depth-first pre-order with respect to their
+ * positions in the DOM.
+ *
+ * Query does not look deep into any subcomponent views.
+ *
+ * Query is updated as part of the change-detection cycle. Since change detection
+ * happens after construction of a directive, QueryList will always be empty when observed in the
+ * constructor.
+ *
+ * The injected object is an unmodifiable live list.
+ * See {@link QueryList} for more details.
  */
 export var Query: QueryFactory = makeParamDecorator(QueryMetadata);
 
+// TODO(alexeagle): remove the duplication of this doc. It is copied from ContentChildrenMetadata.
 /**
- * {@link ContentChildrenMetadata} factory function.
+ * Configures a content query.
+ *
+ * Content queries are set before the `afterContentInit` callback is called.
+ *
+ * ### Example
+ *
+ * ```
+ * @Directive({
+ *   selector: 'someDir'
+ * })
+ * class SomeDir {
+ *   @ContentChildren(ChildDirective) contentChildren: QueryList<ChildDirective>;
+ *
+ *   afterContentInit() {
+ *     // contentChildren is set
+ *   }
+ * }
+ * ```
  */
 export var ContentChildren: ContentChildrenFactory = makePropDecorator(ContentChildrenMetadata);
 
+// TODO(alexeagle): remove the duplication of this doc. It is copied from ContentChildMetadata.
 /**
- * {@link ContentChildMetadata} factory function.
+ * Configures a content query.
+ *
+ * Content queries are set before the `afterContentInit` callback is called.
+ *
+ * ### Example
+ *
+ * ```
+ * @Directive({
+ *   selector: 'someDir'
+ * })
+ * class SomeDir {
+ *   @ContentChild(ChildDirective) contentChild;
+ *
+ *   afterContentInit() {
+ *     // contentChild is set
+ *   }
+ * }
+ * ```
  */
 export var ContentChild: ContentChildFactory = makePropDecorator(ContentChildMetadata);
 
+// TODO(alexeagle): remove the duplication of this doc. It is copied from ViewChildrenMetadata.
 /**
- * {@link ViewChildrenMetadata} factory function.
+ * Configures a view query.
+ *
+ * View queries are set before the `afterViewInit` callback is called.
+ *
+ * ### Example
+ *
+ * ```
+ * @Component({
+ *   selector: 'someDir',
+ *   templateUrl: 'someTemplate',
+ *   directives: [ItemDirective]
+ * })
+ * class SomeDir {
+ *   @ViewChildren(ItemDirective) viewChildren: QueryList<ItemDirective>;
+ *
+ *   afterViewInit() {
+ *     // viewChildren is set
+ *   }
+ * }
+ * ```
  */
 export var ViewChildren: ViewChildrenFactory = makePropDecorator(ViewChildrenMetadata);
 
+// TODO(alexeagle): remove the duplication of this doc. It is copied from ViewChildMetadata.
 /**
- * {@link ViewChildMetadata} factory function.
+ * Configures a view query.
+ *
+ * View queries are set before the `afterViewInit` callback is called.
+ *
+ * ### Example
+ *
+ * ```
+ * @Component({
+ *   selector: 'someDir',
+ *   templateUrl: 'someTemplate',
+ *   directives: [ItemDirective]
+ * })
+ * class SomeDir {
+ *   @ViewChild(ItemDirective) viewChild:ItemDirective;
+ *
+ *   afterViewInit() {
+ *     // viewChild is set
+ *   }
+ * }
+ * ```
  */
 export var ViewChild: ViewChildFactory = makePropDecorator(ViewChildMetadata);
 
+// TODO(alexeagle): remove the duplication of this doc. It is copied from ViewQueryMetadata.
 /**
- * {@link di/ViewQueryMetadata} factory function.
+ * Similar to {@link QueryMetadata}, but querying the component view, instead of
+ * the content children.
+ *
+ * ### Example ([live demo](http://plnkr.co/edit/eNsFHDf7YjyM6IzKxM1j?p=preview))
+ *
+ * ```javascript
+ * @Component({...})
+ * @View({
+ *   template: `
+ *     <item> a </item>
+ *     <item> b </item>
+ *     <item> c </item>
+ *   `
+ * })
+ * class MyComponent {
+ *   shown: boolean;
+ *
+ *   constructor(private @Query(Item) items:QueryList<Item>) {
+ *     items.onChange(() => console.log(items.length));
+ *   }
+ * }
+ * ```
+ *
+ * Supports the same querying parameters as {@link QueryMetadata}, except
+ * `descendants`. This always queries the whole view.
+ *
+ * As `shown` is flipped between true and false, items will contain zero of one
+ * items.
+ *
+ * Specifies that a {@link QueryList} should be injected.
+ *
+ * The injected object is an iterable and observable live list.
+ * See {@link QueryList} for more details.
  */
 export var ViewQuery: QueryFactory = makeParamDecorator(ViewQueryMetadata);
 
+// TODO(alexeagle): remove the duplication of this doc. It is copied from PipeMetadata.
 /**
- * {@link PipeMetadata} factory function.
+ * Declare reusable pipe function.
+ *
+ * ## Example
+ *
+ * ```
+ * @Pipe({
+ *   name: 'lowercase'
+ * })
+ * class Lowercase {
+ *   transform(v, args) { return v.toLowerCase(); }
+ * }
+ * ```
  */
 export var Pipe: PipeFactory = <PipeFactory>makeDecorator(PipeMetadata);
 
+// TODO(alexeagle): remove the duplication of this doc. It is copied from InputMetadata.
 /**
- * {@link InputMetadata} factory function.
+ * Declares a data-bound input property.
  *
- * See {@link InputMetadata}.
+ * Angular automatically updates data-bound properties during change detection.
+ *
+ * `InputMetadata` takes an optional parameter that specifies the name
+ * used when instantiating a component in the template. When not provided,
+ * the name of the decorated property is used.
+ *
+ * ### Example
+ *
+ * The following example creates a component with two input properties.
+ *
+ * ```typescript
+ * @Component({
+ *   selector: 'bank-account',
+ *   template: `
+ *     Bank Name: {{bankName}}
+ *     Account Id: {{id}}
+ *   `
+ * })
+ * class BankAccount {
+ *   @Input() bankName: string;
+ *   @Input('account-id') id: string;
+ *
+ *   // this property is not bound, and won't be automatically updated by Angular
+ *   normalizedBankName: string;
+ * }
+ *
+ * @Component({
+ *   selector: 'app',
+ *   template: `
+ *     <bank-account bank-name="RBC" account-id="4747"></bank-account>
+ *   `,
+ *   directives: [BankAccount]
+ * })
+ * class App {}
+ *
+ * bootstrap(App);
+ * ```
  */
 export var Input: InputFactory = makePropDecorator(InputMetadata);
 
+// TODO(alexeagle): remove the duplication of this doc. It is copied from OutputMetadata.
 /**
- * {@link OutputMetadata} factory function.
+ * Declares an event-bound output property.
  *
- * See {@link OutputMetadata}.
+ * When an output property emits an event, an event handler attached to that event
+ * the template is invoked.
+ *
+ * `OutputMetadata` takes an optional parameter that specifies the name
+ * used when instantiating a component in the template. When not provided,
+ * the name of the decorated property is used.
+ *
+ * ### Example
+ *
+ * ```typescript
+ * @Directive({
+ *   selector: 'interval-dir',
+ * })
+ * class IntervalDir {
+ *   @Output() everySecond = new EventEmitter();
+ *   @Output('everyFiveSeconds') five5Secs = new EventEmitter();
+ *
+ *   constructor() {
+ *     setInterval(() => this.everySecond.next("event"), 1000);
+ *     setInterval(() => this.five5Secs.next("event"), 5000);
+ *   }
+ * }
+ *
+ * @Component({
+ *   selector: 'app',
+ *   template: `
+ *     <interval-dir (every-second)="everySecond()" (every-five-seconds)="everyFiveSeconds()">
+ *     </interval-dir>
+ *   `,
+ *   directives: [IntervalDir]
+ * })
+ * class App {
+ *   everySecond() { console.log('second'); }
+ *   everyFiveSeconds() { console.log('five seconds'); }
+ * }
+ * bootstrap(App);
+ * ```
  */
 export var Output: OutputFactory = makePropDecorator(OutputMetadata);
 
+// TODO(alexeagle): remove the duplication of this doc. It is copied from HostBindingMetadata.
 /**
- * {@link HostBindingMetadata} factory function.
+ * Declares a host property binding.
+ *
+ * Angular automatically checks host property bindings during change detection.
+ * If a binding changes, it will update the host element of the directive.
+ *
+ * `HostBindingMetadata` takes an optional parameter that specifies the property
+ * name of the host element that will be updated. When not provided,
+ * the class property name is used.
+ *
+ * ### Example
+ *
+ * The following example creates a directive that sets the `valid` and `invalid` classes
+ * on the DOM element that has ng-model directive on it.
+ *
+ * ```typescript
+ * @Directive({selector: '[ng-model]'})
+ * class NgModelStatus {
+ *   constructor(public control:NgModel) {}
+ *   @HostBinding('[class.valid]') get valid { return this.control.valid; }
+ *   @HostBinding('[class.invalid]') get invalid { return this.control.invalid; }
+ * }
+ *
+ * @Component({
+ *   selector: 'app',
+ *   template: `<input [(ng-model)]="prop">`,
+ *   directives: [FORM_DIRECTIVES, NgModelStatus]
+ * })
+ * class App {
+ *   prop;
+ * }
+ *
+ * bootstrap(App);
+ * ```
  */
 export var HostBinding: HostBindingFactory = makePropDecorator(HostBindingMetadata);
 
+// TODO(alexeagle): remove the duplication of this doc. It is copied from HostListenerMetadata.
 /**
- * {@link HostListenerMetadata} factory function.
+ * Declares a host listener.
+ *
+ * Angular will invoke the decorated method when the host element emits the specified event.
+ *
+ * If the decorated method returns `false`, then `preventDefault` is applied on the DOM
+ * event.
+ *
+ * ### Example
+ *
+ * The following example declares a directive that attaches a click listener to the button and
+ * counts clicks.
+ *
+ * ```typescript
+ * @Directive({selector: 'button[counting]'})
+ * class CountClicks {
+ *   numberOfClicks = 0;
+ *
+ *   @HostListener('click', ['$event.target'])
+ *   onClick(btn) {
+ *     console.log("button", btn, "number of clicks:", this.numberOfClicks++);
+ *   }
+ * }
+ *
+ * @Component({
+ *   selector: 'app',
+ *   template: `<button counting>Increment</button>`,
+ *   directives: [CountClicks]
+ * })
+ * class App {}
+ *
+ * bootstrap(App);
+ * ```
  */
 export var HostListener: HostListenerFactory = makePropDecorator(HostListenerMetadata);