docs: expose more API to public, document QueryList

Author: mhevery

modules/angular2/src/core/annotations/di.js

@@ -2,11 +2,17 @@ import {CONST} from 'angular2/src/facade/lang';
 import {DependencyAnnotation} from 'angular2/di';
 
 /**
- * The directive can inject an emitter function that would emit events onto the
- * directive host element.
+ * Specifies that a function for emitting events should be injected.
+ *
+ * NOTE: This is changing pre 1.0.
+ * 
+ * The directive can inject an emitter function that would emit events onto the directive host element.
+ * 
+ * @exportedAs angular2/annotations
  */
 export class EventEmitter extends DependencyAnnotation {
   eventName: string;
+
   @CONST()
   constructor(eventName) {
     super();
@@ -19,8 +25,13 @@ export class EventEmitter extends DependencyAnnotation {
 }
 
 /**
- * The directive can inject a property setter that would allow setting this property on the
- * host element
+ * Specifies that a function for setting host properties should be injected.
+ *
+ * NOTE: This is changing pre 1.0.
+ * 
+ * The directive can inject a property setter that would allow setting this property on the host element.
+ *
+ * @exportedAs angular2/annotations
  */
 export class PropertySetter extends DependencyAnnotation {
   propName: string;
@@ -36,7 +47,32 @@ export class PropertySetter extends DependencyAnnotation {
 }
 
 /**
- * The directive can inject the value of an attribute of the host element
+ * Specifies that a constant attribute value should be injected.
+ *
+ * The directive can inject constant string literals of host element attributes.
+ *
+ * ## Example
+ *
+ * suppose we have an `<input>` element and would like to know its `type`.
+ *
+ * ```html
+ * <input type="text">
+ * ```
+ *
+ * A decorator could inject string literal `text` like so:
+ *
+ * ```javascript
+ * @Decorator({
+ *   selector: `input'
+ * })
+ * class InputDecorator {
+ *   constructor(@Attribute('type') type) {
+ *     // type would be `text` in this example
+ *   }
+ * }
+ * ```
+ *
+ * @exportedAs angular2/annotations
  */
 export class Attribute extends DependencyAnnotation {
   attributeName: string;
@@ -56,7 +92,11 @@ export class Attribute extends DependencyAnnotation {
 }
 
 /**
- * The directive can inject an query that would reflect a list of ancestor directives
+ * Specifies that a [QueryList] should be injected.
+ *
+ * See: [QueryList] for usage.
+ *
+ * @exportedAs angular2/annotations
  */
 export class Query extends DependencyAnnotation {
   directive;

modules/angular2/src/core/compiler/query_list.dart renamed to modules/angular2/src/core/compiler/base_query_list.dart

@@ -10,12 +10,12 @@ import 'dart:collection';
  * In the future this class will implement an Observable interface.
  * For now it uses a plain list of observable callbacks.
  */
-class QueryList extends Object with IterableMixin<Directive> {
+class BaseQueryList extends Object with IterableMixin<Directive> {
   List<Directive> _results;
   List _callbacks;
   bool _dirty;
 
-  QueryList(): _results = [], _callbacks = [], _dirty = false;
+  BaseQueryList(): _results = [], _callbacks = [], _dirty = false;
 
   Iterator<Directive> get iterator => _results.iterator;
 

modules/angular2/src/core/compiler/query_list.es6 renamed to modules/angular2/src/core/compiler/base_query_list.es6

@@ -7,8 +7,10 @@ import {Directive} from 'angular2/src/core/annotations/annotations';
  *
  * In the future this class will implement an Observable interface.
  * For now it uses a plain list of observable callbacks.
+ *
+ * @exportedAs angular2/view
  */
-export class QueryList {
+export class BaseQueryList {
   _results: List<Directive>;
   _callbacks;
   _dirty;

modules/angular2/src/core/compiler/compiler.js

@@ -40,7 +40,9 @@ export class CompilerCache {
   }
 }
 
-
+/**
+ * @exportedAs angular2/template
+ */
 @Injectable()
 export class Compiler {
   _reader: DirectiveMetadataReader;

modules/angular2/src/core/compiler/dynamic_component_loader.js

@@ -10,7 +10,9 @@ import {Renderer} from 'angular2/src/render/api';
 import {ElementRef} from './element_injector';
 import {AppView} from './view';
 
-
+/**
+ * @exportedAs angular2/view
+ */
 export class ComponentRef {
   location:ElementRef;
   instance:any;
@@ -34,6 +36,8 @@ export class ComponentRef {
 /**
  * Service for dynamically loading a Component into an arbitrary position in the internal Angular
  * application tree.
+ *
+ * @exportedAs angular2/view
  */
 @Injectable()
 export class DynamicComponentLoader {

modules/angular2/src/core/compiler/element_injector.js

@@ -19,6 +19,9 @@ var _undefined = new Object();
 
 var _staticKeys;
 
+/**
+ * @exportedAs angular2/view
+ */
 export class ElementRef {
   elementInjector:ElementInjector;
 

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

@@ -0,0 +1,83 @@
+import {BaseQueryList} from './base_query_list';
+
+/**
+ * An iterable live list of components in the Light DOM.
+ *
+ * Injectable Objects that contains a live list of child directives in the light DOM of a directive.
+ * The directives are kept in depth-first pre-order traversal of the DOM.
+ *
+ * The `QueryList` is iterable, therefore it can be used in both javascript code with `for..of` loop as well as in
+ * template with `*for="of"` viewport.
+ *
+ * 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 *for="o in 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 `*for` could rearange the list of `<pane>` components which would not be reported to `<tabs>`
+ * component and thus the list of `<pane>` componets would be out of sync with respect to the list of `<pane>` elements.
+ *
+ * A prefferd 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 *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;
+ * }
+ * ```
+ *
+ * @exportedAs angular2/view
+ */
+export class QueryList extends BaseQueryList {
+
+  /**
+   */
+  onChange(callback) {
+    return super.onChange(callback);
+  }
+
+  /**
+   */
+  removeCallback(callback) {
+    return super.removeCallback(callback);
+  }
+
+}

modules/angular2/src/core/compiler/view.js

@@ -13,7 +13,6 @@ import * as renderApi from 'angular2/src/render/api';
 /**
  * Const of making objects: http://jsperf.com/instantiate-size-of-object
  *
- * @exportedAs angular2/template
  */
 @IMPLEMENTS(ChangeDispatcher)
 // TODO(tbosch): this is not supported in dart2js (no '.' is allowed)
@@ -288,7 +287,6 @@ export class AppView {
 
 /**
  *
- * @exportedAs angular2/template
  */
 export class AppProtoView {
   elementBinders:List<ElementBinder>;

modules/angular2/src/test_lib/test_bed.js

@@ -18,7 +18,9 @@ import {DirectiveMetadataReader} from 'angular2/src/core/compiler/directive_meta
 import {queryView, viewRootNodes, el} from './utils';
 import {instantiateType, getTypeOf} from './lang_utils';
 
-
+/**
+ * @exportedAs angular2/test
+ */
 export class TestBed {
   _injector: Injector;
 

modules/angular2/src/test_lib/test_injector.js

@@ -142,6 +142,7 @@ export function createTestInjector(bindings: List) {
  * @param {Array} tokens
  * @param {Function} fn
  * @return {FunctionWithParamTokens}
+ * @exportedAs angular2/test
  */
 export function inject(tokens: List, fn: Function) {
   return new FunctionWithParamTokens(tokens, fn);