docs(compiler): compiler related api docs

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

@@ -70,8 +70,7 @@ export class CompilerCache {
   }
 }
 
-/**
+/*
- *
  * ## URL Resolution
  *
  * ```
@@ -88,9 +87,15 @@ export class CompilerCache {
  * var url = viewAnnotation.templateUrl;
  * var componentUrl = componentUrlMapper.getUrl(componentType);
  * var componentResolvedUrl = urlResolver.resolve(appRootUrl.value, componentUrl);
- * var templateResolvedUrl = urlResolver.resolve(componetResolvedUrl, url);
+ * var templateResolvedUrl = urlResolver.resolve(componentResolvedUrl, url);
  * ```
  */
+/**
+ * Service for compiling {@link Component}s so that they can be later instantiated and their
+ * {@link View}s can be rendered.
+ *
+ * <!-- TODO: check Component and View links, they should likely go to glossary instead -->
+ */
 @Injectable()
 export class Compiler {
   private _compiling: Map<Type, Promise<AppProtoView>> = new Map();
@@ -127,8 +132,10 @@ export class Compiler {
     return PipeBinding.createFromType(typeOrBinding, meta);
   }
 
-  // Create a hostView as if the compiler encountered <hostcmp></hostcmp>.
+  /**
-  // Used for bootstrapping.
+   * Compiles an {@link EntryPointComponent entry-point Component} and returns a promise for a
+   * {@link ProtoViewRef} that can be passed into {@link AppViewManager
+   */
   compileInHost(componentType: Type): Promise<ProtoViewRef> {
     var r = wtfStartTimeRange('Compiler#compile()', stringify(componentType));
 

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

@@ -7,9 +7,8 @@ import {ElementRef} from './element_ref';
 import {ViewRef, HostViewRef} from './view_ref';
 
 /**
- * Angular's reference to a component instance.
+ * Represents a component instance as a node in application's component tree and provides access to
- *
+ * other objects related to this component instance.
- * `ComponentRef` represents a component instance lifecycle and meta information.
  */
 export class ComponentRef {
   /**
@@ -24,7 +23,6 @@ export class ComponentRef {
 
   componentType: Type;
 
-
   injector: Injector;
 
   /**
@@ -54,11 +52,15 @@ export class ComponentRef {
 }
 
 /**
- * Service for dynamically loading a Component into an arbitrary position in the internal Angular
+ * Service for creating an instance of a component and attaching it to the component tree of an
- * application tree.
+ * application at a specified location.
  */
 @Injectable()
 export class DynamicComponentLoader {
+
+  /**
+   * @private
+   */
   constructor(private _compiler: Compiler, private _viewManager: AppViewManager) {}
 
   /**

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

@@ -3,20 +3,28 @@ import {ViewRef} from './view_ref';
 import {RenderViewRef, RenderElementRef, Renderer} from 'angular2/src/core/render/api';
 
 /**
- * An opaque reference to the underlying element.
+ * Represents a location in a View that has an injection, change-detection and render contexts
+ * associated with it.
  *
- * The underlying native element is a DOM Element in a browser context, but may represent other
+ * An `ElementRef` is created for each element in the Template that contains a Directive, Component
- * types on other rendering platforms. In the browser the `ElementRef` can be sent to the Web
+ * or data-binding.
- * Worker. Web Workers can not have references to the DOM Elements.
+ *
+ * An `ElementRef` is backed by a render-specific element. In the browser context, this is usually a
+ * DOM element.
  */
 export class ElementRef implements RenderElementRef {
+
   /**
-   * Reference to the {@link ViewRef} where the `ElementRef` is inside of.
+   * @private
+   *
+   * Reference to the {@link ViewRef} that this `ElementRef` is part of.
    */
   parentView: ViewRef;
 
 
   /**
+   * @private
+   *
    * Index of the element inside the {@link ViewRef}.
    *
    * This is used internally by the Angular framework to locate elements.
@@ -24,12 +32,17 @@ export class ElementRef implements RenderElementRef {
   boundElementIndex: number;
 
   /**
+   * @private
+   *
    * Index of the element inside the `RenderViewRef`.
    *
    * This is used internally by the Angular framework to locate elements.
    */
   renderBoundElementIndex: number;
 
+  /**
+   * @private
+   */
   constructor(parentView: ViewRef, boundElementIndex: number, renderBoundElementIndex: number,
               private _renderer: Renderer) {
     this.parentView = parentView;
@@ -38,7 +51,7 @@ export class ElementRef implements RenderElementRef {
   }
 
   /**
-   *
+   * @private
    */
   get renderView(): RenderViewRef { return this.parentView.render; }
 
@@ -48,15 +61,22 @@ export class ElementRef implements RenderElementRef {
   set renderView(viewRef: RenderViewRef) { throw new BaseException('Abstract setter'); }
 
   /**
-   * Returns the native Element implementation.
+   * The underlying native element or `null` if direct access to native elements is not supported
+   * (e.g. when the application runs in a web worker).
    *
-   * In the browser this represents the DOM element.
+   * <div class="callout is-critical">
-   *
+   *   <header>Use with caution</header>
-   * The `nativeElement` can be used as an escape hatch when direct DOM manipulation is needed. Use
+   *   <p>
-   * this with caution, as it creates tight coupling between your application and the browser, which
+   *    Use this api as the last resort when direct access to DOM is needed. Use templating and
-   * will not work in Web Workers.
+   *    data-binding provided by Angular instead.
-   *
+   *   </p>
-   * NOTE: This method will return null in the webworker scenario!
+   *   <p>
+   *    Relying on direct DOM access creates tight coupling between your application and rendering
+   *    layers which will make it impossible to separate the two and deploy your application in into a
+   *    web worker.
+   *   </p>
+   *   <!-- TODO: add info about custom renderers that should be used instead -->
+   * </div>
    */
   get nativeElement(): any { return this._renderer.getNativeElementSync(this); }
 }

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

@@ -3,17 +3,26 @@ import {ElementRef} from './element_ref';
 import * as viewModule from './view';
 
 /**
- * Reference to a template within a component.
+ * Represents an Embedded Template that can be used for creating Embedded Views.
  *
- * Represents an opaque reference to the underlying template that can
+ * Use {@link ViewContainerRef#createEmbeddedView} method to instantiate an Embedded View and attach
- * be instantiated using the {@link ViewContainerRef}.
+ * it to a View Container.
+ *
+ * <!-- TODO: how to get hold of it? -->
  */
 export class TemplateRef {
+
   /**
-   * The location of the template
+   * The location in the View where the Embedded View logically belong to.
+   *
+   * This `ElementRef` provides the data-binding and injection context for Embedded Views created
+   * from this `TemplateRef`.
    */
   elementRef: ElementRef;
 
+  /**
+   * @private
+   */
   constructor(elementRef: ElementRef) { this.elementRef = elementRef; }
 
   private _getProtoView(): viewModule.AppProtoView {
@@ -23,10 +32,14 @@ export class TemplateRef {
         .nestedProtoView;
   }
 
+  /**
+   * Reference to the ProtoView created by compiling the original Embedded Template, from which the
+   * Embedded View is instatiated.
+   */
   get protoViewRef(): ProtoViewRef { return this._getProtoView().ref; }
 
   /**
-   * Whether this template has a local variable with the given name
+   * Returns true if the Template declares a Local Variable with the given name.
    */
   hasLocal(name: string): boolean { return this._getProtoView().variableBindings.has(name); }
 }

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

@@ -10,17 +10,44 @@ import {TemplateRef} from './template_ref';
 import {ViewRef, HostViewRef, ProtoViewRef, internalView} from './view_ref';
 
 /**
- * A location where {@link ViewRef}s can be attached.
+ * Represents a container where one or more Views can be attached.
  *
- * A `ViewContainerRef` represents a location in a {@link ViewRef} where other child
+ * The container can contain two kinds of Views. Host Views, created by instantiating a
- * {@link ViewRef}s can be inserted. Adding and removing views is the only way of structurally
+ * {@link Component} via {@link #createHostView}s, and Embedded Views, created by instantiating an
- * changing the rendered DOM of the application.
+ * {@link TemplateRef Embedded Template} via {@link #createEmbeddedView}).
+ *
+ * The location of the View Container within the containing View is specified by the Anchor
+ * `element`. Each View Container can have only one Anchor Element and each Anchor Element can only
+ * have a single View Container.
+ *
+ * Root elements of Views attached to this container become siblings of the Anchor Element in
+ * the Rendered View.
+ *
+ * To access a ViewContainerRef of an Element, you can either place a {@link Directive} injected
+ * with `ViewContainerRef` on the Element, or you obtain it via
+ * {@link ViewManager#getViewContainer}.
+ *
+ * <!-- TODO: Is ViewContainerRef#element a public api? Should it be renamed? to anchor or anchorElementRef? -->
+ * <!-- TODO: rename all atIndex params to just index or get(index) to get(atIndex) -->
  */
 export class ViewContainerRef {
+
   /**
    * @private
    */
-  constructor(public viewManager: avmModule.AppViewManager, public element: ElementRef) {}
+  constructor(
+    /**
+     * @private
+     */
+    public viewManager: avmModule.AppViewManager,
+
+    /**
+     * Anchor element that specifies the location of this container in the containing View.
+     */
+    public element: ElementRef
+  ) {
+
+  }
 
   private _getViews(): Array<viewModule.AppView> {
     var vc = internalView(this.element.parentView).viewContainers[this.element.boundElementIndex];
@@ -28,7 +55,7 @@ export class ViewContainerRef {
   }
 
   /**
-   * Remove all {@link ViewRef}s at current location.
+   * Destroys all Views in the container.
    */
   clear(): void {
     for (var i = this.length - 1; i >= 0; i--) {
@@ -37,28 +64,22 @@ export class ViewContainerRef {
   }
 
   /**
-   * Return a {@link ViewRef} at specific index.
+   * Returns the {@link ViewRef} for the View located in this container at the specified index.
    */
   get(index: number): ViewRef { return this._getViews()[index].ref; }
 
   /**
-   * Returns number of {@link ViewRef}s currently attached at this location.
+   * Returns the number of Views currently attached to this container.
    */
   get length(): number { return this._getViews().length; }
 
   /**
-   * Create and insert a {@link ViewRef} into the view-container.
+   * Instantiates an Embedded View based on the {@link TemplateRef `templateRef`} and inserts it
+   * into this container at index specified via `atIndex`.
    *
-   * - `protoViewRef` (optional) {@link ProtoViewRef} - The `ProtoView` to use for creating
+   * If `atIndex` is not specified, the new View will be inserted as the last View in the container.
-   *   `View` to be inserted at this location. If `ViewContainer` is created at a location
-   *   of inline template, then `protoViewRef` is the `ProtoView` of the template.
-   * - `atIndex` (optional) `number` - location of insertion point. (Or at the end if unspecified.)
-   * - `context` (optional) {@link ElementRef} - Context (for expression evaluation) from the
-   *   {@link ElementRef} location. (Or current context if unspecified.)
-   * - `bindings` (optional) Array of {@link ResolvedBinding} - Used for configuring
-   *   `ElementInjector`.
    *
-   * Returns newly created {@link ViewRef}.
+   * Returns the {@link ViewRef} for the newly created View.
    */
   // TODO(rado): profile and decide whether bounds checks should be added
   // to the methods below.
@@ -67,6 +88,20 @@ export class ViewContainerRef {
     return this.viewManager.createEmbeddedViewInContainer(this.element, atIndex, templateRef);
   }
 
+  /**
+   * Instantiates a single {@link Component} and inserts it into this container at index specified
+   * via `atIndex`.
+   *
+   * The component is instantiated using its {@link ProtoViewRef `protoViewRef`} which can be
+   * obtained via {@link Compiler#compileInHost}.
+   *
+   * If `atIndex` is not specified, the new View will be inserted as the last View in the container.
+   *
+   * You can optionally specify `dynamicallyCreatedBindings`, which configure the {@link Injector}
+   * that will be created for the new Host View. <!-- TODO: what is host view? it's never defined!!! -->
+   *
+   * Returns the {@link ViewRef} for the newly created View.
+   */
   createHostView(protoViewRef: ProtoViewRef = null, atIndex: number = -1,
                  dynamicallyCreatedBindings: ResolvedBinding[] = null): HostViewRef {
     if (atIndex == -1) atIndex = this.length;
@@ -75,12 +110,14 @@ export class ViewContainerRef {
   }
 
   /**
-   * Insert a {@link ViewRef} at specefic index.
+   * <!-- TODO: refactor into move and remove -->
+   * Inserts a View identified by a {@link ViewRef} into the container at index specified via
+   * `atIndex`.
    *
-   * The index is location at which the {@link ViewRef} should be attached. If omitted it is
+   * If `atIndex` is not specified, the new View will be inserted as the last View in the container.
-   * inserted at the end.
    *
    * Returns the inserted {@link ViewRef}.
+   * <!-- TODO: why does it return ViewRef? looks useless -->
    */
   insert(viewRef: ViewRef, atIndex: number = -1): ViewRef {
     if (atIndex == -1) atIndex = this.length;
@@ -88,16 +125,17 @@ export class ViewContainerRef {
   }
 
   /**
-   * Return the index of already inserted {@link ViewRef}.
+   * Returns the index of the View, specified via {@link ViewRef}, within the current container.
    */
   indexOf(viewRef: ViewRef): number {
     return ListWrapper.indexOf(this._getViews(), internalView(viewRef));
   }
 
   /**
-   * Remove a {@link ViewRef} at specific index.
+   * <!-- TODO: rename to destroy -->
+   * Destroys a View attached to this container at index specified via `atIndex`.
    *
-   * If the index is omitted last {@link ViewRef} is removed.
+   * If `atIndex` is not specified, the last View in the container will be removed.
    */
   remove(atIndex: number = -1): void {
     if (atIndex == -1) atIndex = this.length - 1;
@@ -106,8 +144,11 @@ export class ViewContainerRef {
   }
 
   /**
-   * The method can be used together with insert to implement a view move, i.e.
+   * <!-- TODO: refactor into move and remove -->
-   * moving the DOM nodes while the directives in the view stay intact.
+   * Use along with {@link #insert} to move a View within the current container.
+   *
+   * If the `atIndex` param is omitted, the last {@link ViewRef} is detached.
+   * <!-- TODO: why does it return ViewRef? looks useless -->
    */
   detach(atIndex: number = -1): ViewRef {
     if (atIndex == -1) atIndex = this.length - 1;

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

@@ -19,9 +19,10 @@ import {AppViewListener} from './view_listener';
 import {wtfCreateScope, wtfLeave, WtfScopeFn} from '../profile/profile';
 
 /**
- * Entry point for creating, moving views in the view hierarchy and destroying views.
+ * Service exposing low level API for creating, moving and destroying Views.
- * This manager contains all recursion and delegates to helper methods
+ *
- * in AppViewManagerUtils and the Renderer, so unit tests get simpler.
+ * Most applications should use higher-level abstractions like {@link DynamicComponentLoader} and
+ * {@link ViewContainerRef} instead.
  */
 @Injectable()
 export class AppViewManager {
@@ -178,6 +179,7 @@ export class AppViewManager {
   _createEmbeddedViewInContainerScope: WtfScopeFn =
       wtfCreateScope('AppViewManager#createEmbeddedViewInContainer()');
   /**
+   * <!-- TODO: why "InContainer"? createRootHostView doesn't use this suffix. seems redundant -->
    *
    * See {@link AppViewManager#destroyViewInContainer}.
    */
@@ -195,6 +197,7 @@ export class AppViewManager {
   _createHostViewInContainerScope: WtfScopeFn =
       wtfCreateScope('AppViewManager#createHostViewInContainer()');
   /**
+   * <!-- TODO: why "InContainer"? createRootHostView doesn't use this suffix. seems redundant -->
    *
    * See {@link AppViewManager#destroyViewInContainer}.
    */
@@ -258,6 +261,7 @@ export class AppViewManager {
 
   _destroyViewInContainerScope = wtfCreateScope('AppViewMananger#destroyViewInContainer()');
   /**
+   * <!-- TODO: why "InContainer"? createRootHostView doesn't use this suffix. seems redundant -->
    *
    * See {@link AppViewManager#createViewInContainer}.
    */
@@ -271,6 +275,7 @@ export class AppViewManager {
 
   _attachViewInContainerScope = wtfCreateScope('AppViewMananger#attachViewInContainer()');
   /**
+   * <!-- TODO: why "InContainer"? createRootHostView doesn't use this suffix. seems redundant -->
    *
    * See {@link AppViewManager#detachViewInContainer}.
    */
@@ -293,6 +298,7 @@ export class AppViewManager {
 
   _detachViewInContainerScope = wtfCreateScope('AppViewMananger#detachViewInContainer()');
   /**
+   * <!-- TODO: why "InContainer"? createRootHostView doesn't use this suffix. seems redundant -->
    *
    * See {@link AppViewManager#attachViewInContainer}.
    */

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

@@ -13,21 +13,31 @@ export function internalProtoView(protoViewRef: ProtoViewRef): viewModule.AppPro
   return isPresent(protoViewRef) ? protoViewRef._protoView : null;
 }
 
-export interface HostViewRef { changeDetectorRef: ChangeDetectorRef; }
+/**
+ * Represents the View of a {@link Component} that was compiled via {@link Compiler#compileInHost
+ */
+export interface HostViewRef {
+  /**
+   * @private
+   */
+  changeDetectorRef: ChangeDetectorRef;
+}
 
 /**
- * A reference to an Angular View.
+ * Represents an Angular View.
  *
- * A View is a fundamental building block of Application UI. A View is the smallest set of
+ * <!-- TODO: move the next two paragraphs to the dev guide -->
- * elements which are created and destroyed together. A View can change properties on the elements
+ * A View is a fundamental building block of the application UI. It is the smallest grouping of
- * within the view, but it can not change the structure of those elements.
+ * Elements which are created and destroyed together.
  *
- * To change structure of the elements, the Views can contain zero or more {@link ViewContainerRef}s
+ * Properties of elements in a View can change, but the structure (number and order) of elements in
- * which allow the views to be nested.
+ * a View cannot. Changing the structure of elements can only be done by inserting, moving or
+ * removing nested Views via a View Container. Each View can contain many View Containers.
+ * <!-- /TODO -->
  *
  * ## Example
  *
- * Given this template
+ * Given this template...
  *
  * ```
  * Count: {{items.length}}
@@ -36,9 +46,9 @@ export interface HostViewRef { changeDetectorRef: ChangeDetectorRef; }
  * </ul>
  * ```
  *
- * The above example we have two {@link ProtoViewRef}s:
+ * ... we have two {@link ProtoViewRef}s:
  *
- * Outter {@link ProtoViewRef}:
+ * Outer {@link ProtoViewRef}:
  * ```
  * Count: {{items.length}}
  * <ul>
@@ -53,7 +63,7 @@ export interface HostViewRef { changeDetectorRef: ChangeDetectorRef; }
  *
  * Notice that the original template is broken down into two separate {@link ProtoViewRef}s.
  *
- * The outter/inner {@link ProtoViewRef}s are then assembled into views like so:
+ * The outer/inner {@link ProtoViewRef}s are then assembled into views like so:
  *
  * ```
  * <!-- ViewRef: outer-0 -->
@@ -85,6 +95,8 @@ export class ViewRef implements HostViewRef {
   get renderFragment(): RenderFragmentRef { return this._view.renderFragment; }
 
   /**
+   * @private
+   *
    * Return `ChangeDetectorRef`
    */
   get changeDetectorRef(): ChangeDetectorRef {
@@ -107,13 +119,14 @@ export class ViewRef implements HostViewRef {
 }
 
 /**
- * A reference to an Angular ProtoView.
+ * Represents Angular's ProtoView.
  *
- * A ProtoView is a reference to a template for easy creation of views.
+ * A ProtoView is a prototypical View that is the result of Template compilation and enables
- * (See {@link AppViewManager#createViewInContainer `AppViewManager#createViewInContainer`} and
+ * Angular to efficiently create an instance of a View based on the compiled Template.
+ *
+ * A ProtoView is created {@link AppViewManager#createViewInContainer} and
  * {@link AppViewManager#createRootHostView `AppViewManager#createRootHostView`}).
  *
- * A `ProtoView` is a factory for creating `View`s.
  *
  * ## Example
  *
@@ -128,7 +141,7 @@ export class ViewRef implements HostViewRef {
  *
  * The above example we have two {@link ProtoViewRef}s:
  *
- * Outter {@link ProtoViewRef}:
+ * Outer {@link ProtoViewRef}:
  * ```
  * Count: {{items.length}}
  * <ul>