refactor: Remove IQueryList

BREAKING CHANGE: Closes angular#3577

Author: mhevery

modules/angular2/core.ts

@@ -16,7 +16,6 @@ export {DirectiveResolver} from 'angular2/src/core/compiler/directive_resolver';
 export {Compiler} from 'angular2/src/core/compiler/compiler';
 
 export {AppViewManager} from 'angular2/src/core/compiler/view_manager';
-export {IQueryList} from 'angular2/src/core/compiler/interface_query';
 export {QueryList} from 'angular2/src/core/compiler/query_list';
 export {DynamicComponentLoader} from 'angular2/src/core/compiler/dynamic_component_loader';
 export {LifeCycle} from 'angular2/src/core/life_cycle/life_cycle';

modules/angular2/src/core/compiler/interface_query.ts

@@ -1,18 +1,78 @@
 library angular2.src.core.compiler.query_list;
 
 import 'dart:collection';
-import './interface_query.dart';
 
 /**
- * Injectable Objects that contains a live list of child directives in the light Dom of a directive.
+ * An iterable and observable live list of components in the DOM.
+ *
+ * A QueryList contains a live list of child directives in the DOM of a directive.
  * The directives are kept in depth-first pre-order traversal of the DOM.
  *
- * In the future this class will implement an Observable interface.
- * For now it uses a plain list of observable callbacks.
+ * The `QueryList` is iterable, therefore it can be used in both javascript code with `for..of` loop
+ * as well as in template with `*ng-for="of"` directive.
+ *
+ * QueryList is updated as part of the change-detection cycle of a directive. Since change detection
+ * happens after construction of a directive, QueryList will always be empty when observed in the
+ * constructor.
+ *
+ *
+ * NOTE: In the future this class will implement an `Observable` interface. For now it uses a plain
+ * list of observable callbacks.
+ *
+ * # Example:
+ *
+ * Assume that `<tabs>` component would like to get a list its children which are `<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>
+ * ```
+ *
+ * In the above example the list of `<tabs>` elements needs to get a list of `<pane>` elements so
+ * that it could render tabs with the correct titles and in the correct order.
+ *
+ * A possible solution would be for a `<pane>` to inject `<tabs>` component and then register itself
+ * with `<tabs>` component's on `hydrate` and deregister on `dehydrate` event. While a reasonable
+ * approach, this would only work partialy since `*ng-for` could rearrange the list of `<pane>`
+ * components which would not be reported to `<tabs>` component and thus the list of `<pane>`
+ * components would be out of sync with respect to the list of `<pane>` elements.
+ *
+ * A preferred solution is to inject a `QueryList` which is a live list of directives in the
+ * component`s light DOM.
+ *
+ * ```javascript
+ * @Component(
+ * selector: 'tabs'
+ * )
+ * @View(
+ * template: `
+ * <ul>
+ * <li *ng-for="#pane of panes">{{pane.title}}</li>
+ * </ul>
+ * <content></content>
+ * `
+ * )
+ * class Tabs {
+ * QueryList<Pane> panes;
+ *
+ * constructor(@Query(Pane) QueryList<Pane> this.panes) { }
+ * }
+ *
+ * @Component(
+ * selector: 'pane',
+ * properties: ['title']
+ * )
+ * @View(...)
+ * class Pane {
+ * String title;
+ * }
+ * ```
  */
 class QueryList<T> extends Object
- with IterableMixin<T>
- implements IQueryList<T> {
+ with IterableMixin<T> {
  List<T> _results = [];
  List _callbacks = [];
  bool _dirty = false;

modules/angular2/src/core/compiler/query_list.dart

@@ -1,14 +1,77 @@
 import {List, ListWrapper, MapWrapper} from 'angular2/src/facade/collection';
-import {IQueryList} from './interface_query';
 
 /**
- * Injectable Objects that contains a live list of child directives in the light Dom of a directive.
+ * An iterable and observable live list of components in the DOM.
+ *
+ * A QueryList contains a live list of child directives in the DOM of a directive.
  * The directives are kept in depth-first pre-order traversal of the DOM.
  *
- * In the future this class will implement an Observable interface.
- * For now it uses a plain list of observable callbacks.
+ * The `QueryList` is iterable, therefore it can be used in both javascript code with `for..of` loop
+ * as well as in template with `*ng-for="of"` directive.
+ *
+ * QueryList is updated as part of the change-detection cycle of a directive. Since change detection
+ * happens after construction of a directive, QueryList will always be empty when observed in the
+ * constructor.
+ *
+ *
+ * NOTE: In the future this class will implement an `Observable` interface. For now it uses a plain
+ * list of observable callbacks.
+ *
+ * # Example:
+ *
+ * Assume that `<tabs>` component would like to get a list its children which are `<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>
+ * ```
+ *
+ * In the above example the list of `<tabs>` elements needs to get a list of `<pane>` elements so
+ * that it could render tabs with the correct titles and in the correct order.
+ *
+ * A possible solution would be for a `<pane>` to inject `<tabs>` component and then register itself
+ * with `<tabs>` component's on `hydrate` and deregister on `dehydrate` event. While a reasonable
+ * approach, this would only work partialy since `*ng-for` could rearrange the list of `<pane>`
+ * components which would not be reported to `<tabs>` component and thus the list of `<pane>`
+ * components would be out of sync with respect to the list of `<pane>` elements.
+ *
+ * A preferred solution is to inject a `QueryList` which is a live list of directives in the
+ * component`s light DOM.
+ *
+ * ```javascript
+ * @Component({
+ * selector: 'tabs'
+ * })
+ * @View({
+ * 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;
+ * }
+ * }
+ *
+ * @Component({
+ * selector: 'pane',
+ * properties: ['title']
+ * })
+ * @View(...)
+ * class Pane {
+ * title:string;
+ * }
+ * ```
  */
-export class QueryList<T> implements IQueryList<T> {
+export class QueryList<T> {
  protected _results: List < T >= [];
  protected _callbacks: List < () => void >= [];
  protected _dirty: boolean = false;