From 096ae7c4045980e1a13d2a83398d33aac1c90e0f Mon Sep 17 00:00:00 2001 From: vsavkin Date: Wed, 14 Sep 2016 11:51:15 -0700 Subject: [PATCH] docs(core): updates query decorator docs --- modules/@angular/core/src/metadata/di.ts | 191 +++++++++-------------- modules/@angular/core/src/type.ts | 4 +- 2 files changed, 76 insertions(+), 119 deletions(-) diff --git a/modules/@angular/core/src/metadata/di.ts b/modules/@angular/core/src/metadata/di.ts index 63c2ff6eb1..d5566e9956 100644 --- a/modules/@angular/core/src/metadata/di.ts +++ b/modules/@angular/core/src/metadata/di.ts @@ -155,7 +155,35 @@ export abstract class Query {} */ export interface ContentChildrenDecorator { /** - * @docsNotRequired + * @whatItDoes Configures a content query. + * + * @howToUse + * + * {@example core/di/ts/contentChildren/content_children_howto.ts region='HowTo'} + * + * @description + * + * You can use ContentChildren to get the {@link QueryList} of elements or directives from the + * content DOM. Any time a child element is added, removed, or moved, the query list will be + * updated, + * and the changes observable of the query list will emit a new value. + * + * Content queries are set before the `ngAfterContentInit` callback is called. + * + * **Metadata Properties**: + * + * * **selector** - the directive type or the name used for querying. + * * **descendants** - include only direct children or all descendants. + * * **read** - read a different token from the queried elements. + * + * Let's look at an example: + * + * {@example core/di/ts/contentChildren/content_children_example.ts region='Component'} + * + * **npm package**: `@angular/core` + * + * @stable + * @Annotation */ (selector: Type|Function|string, {descendants, read}?: {descendants?: boolean, read?: any}): any; @@ -168,60 +196,24 @@ export interface ContentChildrenDecorator { * Type of the ContentChildren metadata. * * @stable + * @Annotation */ export type ContentChildren = Query; /** - * @whatItDoes Configures a content query. + * ContentChildren decorator and metadata. * - * @howToUse - * - * ``` - * import {Directive, QueryList, ContentChildren} from '@angular/core'; - * - * @Directive({ - * selector: 'someDir' - * }) - * class SomeDir { - * @ContentChildren(ChildDirective) contentChildren: QueryList; - * - * ngAfterContentInit() { - * // contentChildren is set - * } - * } - * ``` - * - * @description - * - * You can use ContentChildren to get the {@link QueryList} of elements or directives from the - * content DOM. Any time a child element is added, removed, or moved, the query list will be - * updated, - * and the changes observable of the query list will emit a new value. - * - * Content queries are set before the `ngAfterContentInit` callback is called. - * - * **Metadata Properties**: - * - * * **selector** - the directive type or the name used for querying. - * * **descendants** - include only direct children or all descendants. - * * **read** - read a different token from the queried elements. - * - * Let's look at an example: - * - * {@example core/di/ts/contentChildren/content_children_example.ts region='Component'} - * - * **npm package**: `@angular/core` - * - * @stable - * @Annotation + * @stable + * @Annotation */ -export const ContentChildren: ContentChildrenDecorator = makePropDecorator( - 'ContentChildren', - [ - ['selector', undefined], - {first: false, isViewQuery: false, descendants: false, read: undefined} - ], - Query); +export const ContentChildren: ContentChildrenDecorator = + makePropDecorator( + 'ContentChildren', + [ + ['selector', undefined], + {first: false, isViewQuery: false, descendants: false, read: undefined} + ], + Query); /** * Type of the ContentChild decorator / constructor function. @@ -251,20 +243,7 @@ export type ContentChild = Query; * * @howToUse * - * ``` - * import {Directive, ContentChild} from '@angular/core'; - * - * @Directive({ - * selector: 'someDir' - * }) - * class SomeDir { - * @ContentChild(ChildDirective) contentChild; - * - * ngAfterContentInit() { - * // contentChild is set - * } - * } - * ``` + * {@example core/di/ts/contentChild/content_child_howto.ts region='HowTo'} * * @description * @@ -326,21 +305,7 @@ export type ViewChildren = Query; * * @howToUse * - * ``` - * import {Component, QueryList, ViewChildren} from '@angular/core'; - * - * @Component({ - * selector: 'someCmp', - * templateUrl: 'someCmp.html' - * }) - * class SomeCmp { - * @ViewChildren(ChildDirective) viewChildren: QueryList; - * - * ngAfterViewInit() { - * // viewChildren is set - * } - * } - * ``` + * {@example core/di/ts/viewChildren/view_children_howto.ts region='HowTo'} * * @description * @@ -386,8 +351,35 @@ export const ViewChildren: ViewChildrenDecorator = makePropDecorator( */ export interface ViewChildDecorator { /** - * @docsNotRequired - */ (selector: Type|Function|string, {read}?: {read?: any}): any; + * @whatItDoes Configures a view query. + * + * @howToUse + * + * {@example core/di/ts/viewChild/view_child_howto.ts region='HowTo'} + * + * @description + * + * You can use ViewChild to get the first element or the directive matching the selector from the + * view DOM. If the view DOM changes, and a new child matches the selector, + * the property will be updated. + * + * View queries are set before the `ngAfterViewInit` callback is called. + * + * **Metadata Properties**: + * + * * **selector** - the directive type or the name used for querying. + * * **read** - read a different token from the queried elements. + * + * Let's look at an example!!!!: + * + * {@example core/di/ts/viewChild/view_child_example.ts region='Component'} + * + * **npm package**: `@angular/core` + * + * @stable + * @Annotation + */ + (selector: Type|Function|string, {read}?: {read?: any}): any; new (selector: Type|Function|string, {read}?: {read?: any}): ViewChild; } @@ -399,44 +391,7 @@ export interface ViewChildDecorator { export type ViewChild = Query; /** - * @whatItDoes Configures a view query. - * - * @howToUse - * - * ``` - * import {Component, QueryList, ViewChild} from '@angular/core'; - * - * @Component({ - * selector: 'someCmp', - * templateUrl: 'someCmp.html' - * }) - * class SomeCmp { - * @ViewChild(ChildDirective) child: ChildDirective; - * - * ngAfterViewInit() { - * // child is set - * } - * } - * ``` - * - * @description - * - * You can use ViewChild to get the first element or the directive matching the selector from the - * view DOM. If the view DOM changes, and a new child matches the selector, - * the property will be updated. - * - * View queries are set before the `ngAfterViewInit` callback is called. - * - * **Metadata Properties**: - * - * * **selector** - the directive type or the name used for querying. - * * **read** - read a different token from the queried elements. - * - * Let's look at an example: - * - * {@example core/di/ts/viewChild/view_child_example.ts region='Component'} - * - * **npm package**: `@angular/core` + * ViewChild decorator and metadata. * * @stable * @Annotation diff --git a/modules/@angular/core/src/type.ts b/modules/@angular/core/src/type.ts index 040f86a0af..2ea9323a05 100644 --- a/modules/@angular/core/src/type.ts +++ b/modules/@angular/core/src/type.ts @@ -7,7 +7,9 @@ */ /** - * Runtime representation a type that a Component or other object is instances of. + * @whatItDoes Represents a type that a Component or other object is instances of. + * + * @description * * An example of a `Type` is `MyCustomComponent` class, which in JavaScript is be represented by * the `MyCustomComponent` constructor function.