From e9f7a0091032223cf0011ad934dc778c25eca085 Mon Sep 17 00:00:00 2001
From: laco0416 <laco0416+github@gmail.com>
Date: Fri, 19 Feb 2016 15:31:27 +0900
Subject: [PATCH] docs(metadata): Add more docs of ViewChild and ViewChildren

Closes #7174
---
 modules/angular2/src/core/metadata.ts    | 136 ++++++++++++++++++++---
 modules/angular2/src/core/metadata/di.ts | 134 +++++++++++++++++++---
 2 files changed, 238 insertions(+), 32 deletions(-)

diff --git a/modules/angular2/src/core/metadata.ts b/modules/angular2/src/core/metadata.ts
index fc671a12eb..e3ae829e2b 100644
--- a/modules/angular2/src/core/metadata.ts
+++ b/modules/angular2/src/core/metadata.ts
@@ -1093,51 +1093,155 @@ export var ContentChild: ContentChildFactory = makePropDecorator(ContentChildMet
 
 // TODO(alexeagle): remove the duplication of this doc. It is copied from ViewChildrenMetadata.
 /**
- * Configures a view query.
+ * Declares a list of child element references.
  *
- * View queries are set before the `ngAfterViewInit` callback is called.
+ * Angular automatically updates the list when the DOM was updated.
+ *
+ * `ViewChildren` takes a argument to select elements.
+ *
+ * - If the argument is a type, directives or components with the type will be bound.
+ *
+ * - If the argument is a string, the string behaviors as comma-separated selectors. For each
+ * selector, an element matched template variables (e.g. `#child`) will be bound.
+ *
+ * View children are set before the `ngAfterViewInit` callback is called.
  *
  * ### Example
  *
+ * With type selector:
+ *
  * ```
  * @Component({
- *   selector: 'someDir',
- *   templateUrl: 'someTemplate',
- *   directives: [ItemDirective]
+ *   selector: 'child-cmp',
+ *   template: '<p>child</p>'
  * })
- * class SomeDir {
- *   @ViewChildren(ItemDirective) viewChildren: QueryList<ItemDirective>;
+ * class ChildCmp {
+ *   doSomething() {}
+ * }
+ *
+ * @Component({
+ *   selector: 'some-cmp',
+ *   template: `
+ *     <child-cmp></child-cmp>
+ *     <child-cmp></child-cmp>
+ *     <child-cmp></child-cmp>
+ *   `,
+ *   directives: [ChildCmp]
+ * })
+ * class SomeCmp {
+ *   @ViewChildren(ChildCmp) children:QueryList<ChildCmp>;
  *
  *   ngAfterViewInit() {
- *     // viewChildren is set
+ *     // children are set
+ *     this.children.toArray().forEach((child)=>child.doSomething());
  *   }
  * }
  * ```
+ *
+ * With string selector:
+ *
+ * ```
+ * @Component({
+ *   selector: 'child-cmp',
+ *   template: '<p>child</p>'
+ * })
+ * class ChildCmp {
+ *   doSomething() {}
+ * }
+ *
+ * @Component({
+ *   selector: 'some-cmp',
+ *   template: `
+ *     <child-cmp #child1></child-cmp>
+ *     <child-cmp #child2></child-cmp>
+ *     <child-cmp #child3></child-cmp>
+ *   `,
+ *   directives: [ChildCmp]
+ * })
+ * class SomeCmp {
+ *   @ViewChildren('child1,child2,child3') children:QueryList<ChildCmp>;
+ *
+ *   ngAfterViewInit() {
+ *     // children are set
+ *     this.children.toArray().forEach((child)=>child.doSomething());
+ *   }
+ * }
+ * ```
+ *
+ * See also: [ViewChildrenMetadata]
  */
 export var ViewChildren: ViewChildrenFactory = makePropDecorator(ViewChildrenMetadata);
 
 // TODO(alexeagle): remove the duplication of this doc. It is copied from ViewChildMetadata.
 /**
- * Configures a view query.
+ * Declares a reference of child element.
  *
- * View queries are set before the `ngAfterViewInit` callback is called.
+ * `ViewChildren` takes a argument to select elements.
+ *
+ * - If the argument is a type, a directive or a component with the type will be bound.
+ *
+ * - If the argument is a string, the string behaviors as a selectors. An element matched template
+ * variables (e.g. `#child`) will be bound.
+ *
+ * In either case, `@ViewChild()` assigns the first (looking from above) element if the result is
+ * multiple.
+ *
+ * View child is set before the `ngAfterViewInit` callback is called.
  *
  * ### Example
  *
+ * With type selector:
+ *
  * ```
  * @Component({
- *   selector: 'someDir',
- *   templateUrl: 'someTemplate',
- *   directives: [ItemDirective]
+ *   selector: 'child-cmp',
+ *   template: '<p>child</p>'
  * })
- * class SomeDir {
- *   @ViewChild(ItemDirective) viewChild:ItemDirective;
+ * class ChildCmp {
+ *   doSomething() {}
+ * }
+ *
+ * @Component({
+ *   selector: 'some-cmp',
+ *   template: '<child-cmp></child-cmp>',
+ *   directives: [ChildCmp]
+ * })
+ * class SomeCmp {
+ *   @ViewChild(ChildCmp) child:ChildCmp;
  *
  *   ngAfterViewInit() {
- *     // viewChild is set
+ *     // child is set
+ *     this.child.doSomething();
  *   }
  * }
  * ```
+ *
+ * With string selector:
+ *
+ * ```
+ * @Component({
+ *   selector: 'child-cmp',
+ *   template: '<p>child</p>'
+ * })
+ * class ChildCmp {
+ *   doSomething() {}
+ * }
+ *
+ * @Component({
+ *   selector: 'some-cmp',
+ *   template: '<child-cmp #child></child-cmp>',
+ *   directives: [ChildCmp]
+ * })
+ * class SomeCmp {
+ *   @ViewChild('child') child:ChildCmp;
+ *
+ *   ngAfterViewInit() {
+ *     // child is set
+ *     this.child.doSomething();
+ *   }
+ * }
+ * ```
+ * See also: [ViewChildMetadata]
  */
 export var ViewChild: ViewChildFactory = makePropDecorator(ViewChildMetadata);
 
diff --git a/modules/angular2/src/core/metadata/di.ts b/modules/angular2/src/core/metadata/di.ts
index aa77c837dc..e3b6e49423 100644
--- a/modules/angular2/src/core/metadata/di.ts
+++ b/modules/angular2/src/core/metadata/di.ts
@@ -285,23 +285,77 @@ export class ViewQueryMetadata extends QueryMetadata {
 }
 
 /**
- * Configures a view query.
+ * Declares a list of child element references.
  *
- * View queries are set before the `ngAfterViewInit` callback is called.
+ * Angular automatically updates the list when the DOM was updated.
+ *
+ * `ViewChildren` takes an argument to select elements.
+ *
+ * - If the argument is a type, directives or components with the type will be bound.
+ *
+ * - If the argument is a string, the string behaviors as comma-separated selectors. For each
+ * selector, an element matched template variables (e.g. `#child`) will be bound.
+ *
+ * View children are set before the `ngAfterViewInit` callback is called.
  *
  * ### Example
  *
+ * With type selector:
+ *
  * ```
  * @Component({
- *   selector: 'someDir',
- *   templateUrl: 'someTemplate',
- *   directives: [ItemDirective]
+ *   selector: 'child-cmp',
+ *   template: '<p>child</p>'
  * })
- * class SomeDir {
- *   @ViewChildren(ItemDirective) viewChildren: QueryList<ItemDirective>;
+ * class ChildCmp {
+ *   doSomething() {}
+ * }
+ *
+ * @Component({
+ *   selector: 'some-cmp',
+ *   template: `
+ *     <child-cmp></child-cmp>
+ *     <child-cmp></child-cmp>
+ *     <child-cmp></child-cmp>
+ *   `,
+ *   directives: [ChildCmp]
+ * })
+ * class SomeCmp {
+ *   @ViewChildren(ChildCmp) children:QueryList<ChildCmp>;
  *
  *   ngAfterViewInit() {
- *     // viewChildren is set
+ *     // children are set
+ *     this.children.toArray().forEach((child)=>child.doSomething());
+ *   }
+ * }
+ * ```
+ *
+ * With string selector:
+ *
+ * ```
+ * @Component({
+ *   selector: 'child-cmp',
+ *   template: '<p>child</p>'
+ * })
+ * class ChildCmp {
+ *   doSomething() {}
+ * }
+ *
+ * @Component({
+ *   selector: 'some-cmp',
+ *   template: `
+ *     <child-cmp #child1></child-cmp>
+ *     <child-cmp #child2></child-cmp>
+ *     <child-cmp #child3></child-cmp>
+ *   `,
+ *   directives: [ChildCmp]
+ * })
+ * class SomeCmp {
+ *   @ViewChildren('child1,child2,child3') children:QueryList<ChildCmp>;
+ *
+ *   ngAfterViewInit() {
+ *     // children are set
+ *     this.children.toArray().forEach((child)=>child.doSomething());
  *   }
  * }
  * ```
@@ -312,23 +366,71 @@ export class ViewChildrenMetadata extends ViewQueryMetadata {
 }
 
 /**
- * Configures a view query.
  *
- * View queries are set before the `ngAfterViewInit` callback is called.
+ * Declares a reference of child element.
+ *
+ * `ViewChildren` takes an argument to select elements.
+ *
+ * - If the argument is a type, a directive or a component with the type will be bound.
+ *
+ * - If the argument is a string, the string behaviors as a selectors. An element matched template
+ * variables (e.g. `#child`) will be bound.
+ *
+ * In either case, `@ViewChild()` assigns the first (looking from above) element if the result is
+ * multiple.
+ *
+ * View child is set before the `ngAfterViewInit` callback is called.
  *
  * ### Example
  *
+ * With type selector:
+ *
  * ```
  * @Component({
- *   selector: 'someDir',
- *   templateUrl: 'someTemplate',
- *   directives: [ItemDirective]
+ *   selector: 'child-cmp',
+ *   template: '<p>child</p>'
  * })
- * class SomeDir {
- *   @ViewChild(ItemDirective) viewChild:ItemDirective;
+ * class ChildCmp {
+ *   doSomething() {}
+ * }
+ *
+ * @Component({
+ *   selector: 'some-cmp',
+ *   template: '<child-cmp></child-cmp>',
+ *   directives: [ChildCmp]
+ * })
+ * class SomeCmp {
+ *   @ViewChild(ChildCmp) child:ChildCmp;
  *
  *   ngAfterViewInit() {
- *     // viewChild is set
+ *     // child is set
+ *     this.child.doSomething();
+ *   }
+ * }
+ * ```
+ *
+ * With string selector:
+ *
+ * ```
+ * @Component({
+ *   selector: 'child-cmp',
+ *   template: '<p>child</p>'
+ * })
+ * class ChildCmp {
+ *   doSomething() {}
+ * }
+ *
+ * @Component({
+ *   selector: 'some-cmp',
+ *   template: '<child-cmp #child></child-cmp>',
+ *   directives: [ChildCmp]
+ * })
+ * class SomeCmp {
+ *   @ViewChild('child') child:ChildCmp;
+ *
+ *   ngAfterViewInit() {
+ *     // child is set
+ *     this.child.doSomething();
  *   }
  * }
  * ```