docs(compiler): compiler/view related api docs

Closes #4268

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

@@ -91,10 +91,11 @@ export class CompilerCache {
  * ```
  */
 /**
- * Service for compiling {@link Component}s so that they can be later instantiated and their
+ * Low-level service for compiling {@link Component}s into {@link ProtoViewRef ProtoViews}s, which
- * {@link View}s can be rendered.
+ * can later be used to create and render a Component instance.
  *
- * <!-- TODO: check Component and View links, they should likely go to glossary instead -->
+ * Most applications should instead use higher-level {@link DynamicComponentLoader} service, which
+ * both compiles and instantiates a Component.
  */
 @Injectable()
 export class Compiler {
@@ -133,8 +134,10 @@ export class Compiler {
   }
 
   /**
-   * Compiles an {@link EntryPointComponent entry-point Component} and returns a promise for a
+   * Compiles a {@link Component} and returns a promise for this component's {@link ProtoViewRef}.
-   * {@link ProtoViewRef} that can be passed into {@link AppViewManager
+   *
+   * Returns `ProtoViewRef` that can be later used to instantiate a component via
+   * {@link ViewContainerRef#createHostView} or {@link AppViewManager#createHostViewInContainer}.
    */
   compileInHost(componentType: Type): Promise<ProtoViewRef> {
     var r = wtfStartTimeRange('Compiler#compile()', stringify(componentType));

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

@@ -7,26 +7,44 @@ import {ElementRef} from './element_ref';
 import {ViewRef, HostViewRef} from './view_ref';
 
 /**
- * Represents a component instance as a node in application's component tree and provides access to
+ * Represents an instance of a Component created via {@link DynamicComponentLoader}.
- * other objects related to this component instance.
+ *
+ * `ComponentRef` provides access to the Component Instance as well other objects related to this
+ * Component Instance and allows you to destroy the Component Instance via the {@link #dispose}
+ * method.
  */
 export class ComponentRef {
   /**
-   * Location of the component host element.
+   * Location of the Host Element of this Component Instance.
    */
   location: ElementRef;
 
   /**
-   * Instance of component.
+   * The instance of the Component.
    */
   instance: any;
 
+  /**
+   * The user defined component type, represented via the constructor function.
+   *
+   * <!-- TODO: customize wording for Dart docs -->
+   */
   componentType: Type;
 
+  /**
+   * @private
+   *
+   * The injector provided {@link DynamicComponentLoader#loadAsRoot}.
+   *
+   * TODO(i): this api is useless and should be replaced by an injector retrieved from
+   *     the HostElementRef, which is currently not possible.
+   */
   injector: Injector;
 
   /**
    * @private
+   *
+   * TODO(i): refactor into public/private fields
    */
   constructor(location: ElementRef, instance: any, componentType: Type, injector: Injector,
               private _dispose: () => void) {
@@ -37,42 +55,61 @@ export class ComponentRef {
   }
 
   /**
-   * Returns the host {@link ViewRef}.
+   * The {@link ViewRef} of the Host View of this Component instance.
    */
   get hostView(): HostViewRef { return this.location.parentView; }
 
+  /**
+   * @private
+   *
+   * Returns the type of this Component instance.
+   *
+   * TODO(i): this api should be removed
+   */
   get hostComponentType(): Type { return this.componentType; }
 
+  /**
+   * @private
+   *
+   * The instance of the component.
+   *
+   * TODO(i): this api should be removed
+   */
   get hostComponent(): any { return this.instance; }
 
   /**
-   * Dispose of the component instance.
+   * Destroys the component instance and all of the data structures associated with it.
+   *
+   * TODO(i): rename to destroy to be consistent with AppViewManager and ViewContainerRef
    */
   dispose() { this._dispose(); }
 }
 
 /**
- * Service for creating an instance of a component and attaching it to the component tree of an
+ * Service for instantiating a Component and attaching it to a View at a specified location.
- * application at a specified location.
  */
 @Injectable()
 export class DynamicComponentLoader {
-
   /**
    * @private
    */
   constructor(private _compiler: Compiler, private _viewManager: AppViewManager) {}
 
   /**
-   * Loads a root component that is placed at the first element that matches the component's
+   * Creates an instance of a Component `type` and attaches it to the first element in the
-   * selector.
+   * platform-specific global view that matches the component's selector.
    *
-   * - `typeOrBinding` `Type` - representing the component to load.
+   * In a browser the platform-specific global view is the main DOM Document.
-   * - `overrideSelector` (optional) selector to load the component at (or use
-   *   `@Component.selector`) The selector can be anywhere (i.e. outside the current component.)
-   * - `injector` {@link Injector} - optional injector to use for the component.
    *
-   * The loaded component receives injection normally as a hosted view.
+   * If needed, the component's selector can be overridden via `overrideSelector`.
+   *
+   * You can optionally provide `injector` and this {@link Injector} will be used to instantiate the
+   * Component.
+   *
+   * To be notified when this Component instance is destroyed, you can also optionally provide
+   * `onDispose` callback.
+   *
+   * Returns a promise for the {@link ComponentRef} representing the newly created Component.
    *
    *
    * ## Example
@@ -137,10 +174,18 @@ export class DynamicComponentLoader {
   }
 
   /**
-   * Loads a component into the component view of the provided ElementRef next to the element
+   * Creates an instance of a Component and attaches it to a View Container located inside of the
-   * with the given name.
+   * Component View of another Component instance.
+   *
+   * The targeted Component Instance is specified via its `hostLocation` {@link ElementRef}. The
+   * location within the Component View of this Component Instance is specified via `anchorName`
+   * Template Variable Name.
+   *
+   * You can optionally provide `bindings` to configure the {@link Injector} provisioned for this
+   * Component Instance.
+   *
+   * Returns a promise for the {@link ComponentRef} representing the newly created Component.
    *
-   * The loaded component receives injection normally as a hosted view.
    *
    * ## Example
    *
@@ -190,9 +235,13 @@ export class DynamicComponentLoader {
   }
 
   /**
-   * Loads a component next to the provided ElementRef.
+   * Creates an instance of a Component and attaches it to the View Container found at the
+   * `location` specified as {@link ElementRef}.
    *
-   * The loaded component receives injection normally as a hosted view.
+   * You can optionally provide `bindings` to configure the {@link Injector} provisioned for this
+   * Component Instance.
+   *
+   * Returns a promise for the {@link ComponentRef} representing the newly created Component.
    *
    *
    * ## Example
@@ -216,7 +265,7 @@ export class DynamicComponentLoader {
    * })
    * class MyApp {
    *   constructor(dynamicComponentLoader: ng.DynamicComponentLoader, elementRef: ng.ElementRef) {
-   *     dynamicComponentLoader.loadIntoLocation(ChildComponent, elementRef, 'child');
+   *     dynamicComponentLoader.loadNextToLocation(ChildComponent, elementRef);
    *   }
    * }
    *

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

@@ -3,17 +3,16 @@ import {ViewRef} from './view_ref';
 import {RenderViewRef, RenderElementRef, Renderer} from 'angular2/src/core/render/api';
 
 /**
- * Represents a location in a View that has an injection, change-detection and render contexts
+ * Represents a location in a View that has an injection, change-detection and render context
  * associated with it.
  *
  * An `ElementRef` is created for each element in the Template that contains a Directive, Component
  * or data-binding.
  *
- * An `ElementRef` is backed by a render-specific element. In the browser context, this is usually a
+ * An `ElementRef` is backed by a render-specific element. In the browser, this is usually a DOM
- * DOM element.
+ * element.
  */
 export class ElementRef implements RenderElementRef {
-
   /**
    * @private
    *
@@ -72,7 +71,7 @@ export class ElementRef implements RenderElementRef {
    *   </p>
    *   <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
+   *    layers which will make it impossible to separate the two and deploy your application into a
    *    web worker.
    *   </p>
    *   <!-- TODO: add info about custom renderers that should be used instead -->

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

@@ -3,21 +3,30 @@ import {ElementRef} from './element_ref';
 import * as viewModule from './view';
 
 /**
- * Represents an Embedded Template that can be used for creating Embedded Views.
+ * Represents an Embedded Template that can be used to instantiate Embedded Views.
  *
- * Use {@link ViewContainerRef#createEmbeddedView} method to instantiate an Embedded View and attach
+ * You can access a `TemplateRef`, in two ways. Via a directive placed on a `<template>` element (or
- * it to a View Container.
+ * directive prefixed with `*`) and have the `TemplateRef` for this Embedded View injected into the
+ * constructor of the directive using the `TemplateRef` Token. Alternatively you can query for the
+ * `TemplateRef` from a Component or a Directive via {@link Query}.
  *
- * <!-- TODO: how to get hold of it? -->
+ * To instantiate Embedded Views based on a Template, use
+ * {@link ViewContainerRef#createEmbeddedView}, which will create the View and attach it to the
+ * View Container.
  */
 export class TemplateRef {
-
   /**
-   * The location in the View where the Embedded View logically belong to.
+   * The location in the View where the Embedded View logically belongs to.
+   *
+   * The data-binding and injection contexts of Embedded Views created from this `TemplateRef`
+   * inherit from the contexts of this location.
+   *
+   * Typically new Embedded Views are attached to the View Container of this location, but in
+   * advanced use-cases, the View can be attached to a different container while keeping the
+   * data-binding and injection context from the original location.
    *
-   * This `ElementRef` provides the data-binding and injection context for Embedded Views created
-   * from this `TemplateRef`.
    */
+  // TODO(i): rename to anchor or location
   elementRef: ElementRef;
 
   /**
@@ -33,13 +42,15 @@ export class TemplateRef {
   }
 
   /**
-   * Reference to the ProtoView created by compiling the original Embedded Template, from which the
+   * @private
-   * Embedded View is instatiated.
+   *
+   * Reference to the ProtoView used for creating Embedded Views that are based on the compiled
+   * Embedded Template.
    */
   get protoViewRef(): ProtoViewRef { return this._getProtoView().ref; }
 
   /**
-   * Returns true if the Template declares a Local Variable with the given name.
+   * Allows you to check if this Embedded Template defines Local Variable with name matching `name`.
    */
   hasLocal(name: string): boolean { return this._getProtoView().variableBindings.has(name); }
 }

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

@@ -13,8 +13,8 @@ import {ViewRef, HostViewRef, ProtoViewRef, internalView} from './view_ref';
  * Represents a container where one or more Views can be attached.
  *
  * The container can contain two kinds of Views. Host Views, created by instantiating a
- * {@link Component} via {@link #createHostView}s, and Embedded Views, created by instantiating an
+ * {@link Component} via {@link #createHostView}, and Embedded Views, created by instantiating an
- * {@link TemplateRef Embedded Template} via {@link #createEmbeddedView}).
+ * {@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
@@ -23,14 +23,13 @@ import {ViewRef, HostViewRef, ProtoViewRef, internalView} from './view_ref';
  * 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
+ * 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}.
+ * {@link AppViewManager#getViewContainer}.
  *
- * <!-- TODO: Is ViewContainerRef#element a public api? Should it be renamed? to anchor or anchorElementRef? -->
+ * <!-- TODO(i): we are also considering ElementRef#viewContainer api -->
  */
 export class ViewContainerRef {
-
   /**
    * @private
    */
@@ -42,11 +41,9 @@ export class ViewContainerRef {
 
       /**
        * Anchor element that specifies the location of this container in the containing View.
+       * <!-- TODO: rename to anchorElement -->
        */
-    public element: ElementRef
+      public element: ElementRef) {}
-  ) {
-
-  }
 
   private _getViews(): Array<viewModule.AppView> {
     var vc = internalView(this.element.parentView).viewContainers[this.element.boundElementIndex];
@@ -54,7 +51,7 @@ export class ViewContainerRef {
   }
 
   /**
-   * Destroys all Views in the container.
+   * Destroys all Views in this container.
    */
   clear(): void {
     for (var i = this.length - 1; i >= 0; i--) {
@@ -88,18 +85,18 @@ export class ViewContainerRef {
   }
 
   /**
-   * Instantiates a single {@link Component} and inserts it into this container at the specified
+   * Instantiates a single {@link Component} and inserts its Host View into this container at the
-   * `index`.
+   * specified `index`.
    *
-   * The component is instantiated using its {@link ProtoViewRef `protoViewRef`} which can be
+   * The component is instantiated using its {@link ProtoViewRef `protoView`} which can be
    * obtained via {@link Compiler#compileInHost}.
    *
    * If `index` 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!!! -->
+   * that will be created for the Host View.
    *
-   * Returns the {@link ViewRef} for the newly created View.
+   * Returns the {@link HostViewRef} of the Host View created for the newly instantiated Component.
    */
   createHostView(protoViewRef: ProtoViewRef = null, index: number = -1,
                  dynamicallyCreatedBindings: ResolvedBinding[] = null): HostViewRef {
@@ -109,32 +106,32 @@ export class ViewContainerRef {
   }
 
   /**
-   * <!-- TODO: refactor into move and remove -->
    * Inserts a View identified by a {@link ViewRef} into the container at the specified `index`.
    *
    * If `index` is not specified, the new View will be inserted as the last View in the container.
    *
    * Returns the inserted {@link ViewRef}.
-   * <!-- TODO: why does it return ViewRef? looks useless -->
    */
+  // TODO(i): refactor insert+remove into move
   insert(viewRef: ViewRef, index: number = -1): ViewRef {
     if (index == -1) index = this.length;
     return this.viewManager.attachViewInContainer(this.element, index, viewRef);
   }
 
   /**
-   * Returns the index of the View, specified via {@link ViewRef}, within the current container.
+   * Returns the index of the View, specified via {@link ViewRef}, within the current container or
+   * `-1` if this container doesn't contain the View.
    */
   indexOf(viewRef: ViewRef): number {
     return ListWrapper.indexOf(this._getViews(), internalView(viewRef));
   }
 
   /**
-   * <!-- TODO: rename to destroy -->
    * Destroys a View attached to this container at the specified `index`.
    *
    * If `index` is not specified, the last View in the container will be removed.
    */
+  // TODO(i): rename to destroy
   remove(index: number = -1): void {
     if (index == -1) index = this.length - 1;
     this.viewManager.destroyViewInContainer(this.element, index);
@@ -142,12 +139,11 @@ export class ViewContainerRef {
   }
 
   /**
-   * <!-- TODO: refactor into move and remove -->
    * Use along with {@link #insert} to move a View within the current container.
    *
    * If the `index` param is omitted, the last {@link ViewRef} is detached.
-   * <!-- TODO: why does it return ViewRef? looks useless -->
    */
+  // TODO(i): refactor insert+remove into move
   detach(index: number = -1): ViewRef {
     if (index == -1) index = this.length - 1;
     return this.viewManager.detachViewInContainer(this.element, index);

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

@@ -33,7 +33,7 @@ export class AppViewManager {
               private _utils: AppViewManagerUtils, private _renderer: Renderer) {}
 
   /**
-   * Returns a {@link ViewContainerRef} at the {@link ElementRef} location.
+   * Returns a {@link ViewContainerRef} of the View Container at the specified location.
    */
   getViewContainer(location: ElementRef): ViewContainerRef {
     var hostView = internalView(location.parentView);
@@ -41,7 +41,7 @@ export class AppViewManager {
   }
 
   /**
-   * Return the first child element of the host element view.
+   * Returns the {@link ElementRef} that makes up the specified Host View.
    */
   getHostElement(hostViewRef: HostViewRef): ElementRef {
     var hostView = internalView(<ViewRef>hostViewRef);
@@ -52,13 +52,11 @@ export class AppViewManager {
   }
 
   /**
-   * Returns an ElementRef for the element with the given variable name
+   * Searches the Component View of the Component specified via `hostLocation` and returns the
-   * in the current view.
+   * {@link ElementRef} for the Element identified via a Variable Name `variableName`.
    *
-   * - `hostLocation`: {@link ElementRef} of any element in the View which defines the scope of
+   * Throws an exception if the specified `hostLocation` is not a Host Element of a Component, or if
-   *   search.
+   * variable `variableName` couldn't be found in the Component View of this Component.
-   * - `variableName`: Name of the variable to locate.
-   * - Returns {@link ElementRef} of the found element or null. (Throws if not found.)
    */
   getNamedElementInComponentView(hostLocation: ElementRef, variableName: string): ElementRef {
     var hostView = internalView(hostLocation.parentView);
@@ -75,10 +73,7 @@ export class AppViewManager {
   }
 
   /**
-   * Returns the component instance for a given element.
+   * Returns the component instance for the provided Host Element.
-   *
-   * The component is the execution context as seen by an expression at that {@link ElementRef}
-   * location.
    */
   getComponent(hostLocation: ElementRef): any {
     var hostView = internalView(hostLocation.parentView);
@@ -88,19 +83,17 @@ export class AppViewManager {
 
   _createRootHostViewScope: WtfScopeFn = wtfCreateScope('AppViewManager#createRootHostView()');
   /**
-   * Load component view into existing element.
+   * Creates an instance of a Component and attaches it to the first element in the global View
+   * (usually DOM Document) that matches the component's selector or `overrideSelector`.
    *
-   * Use this if a host element is already in the DOM and it is necessary to upgrade
+   * This as a low-level way to bootstrap an application and upgrade an existing Element to a
-   * the element into Angular component by attaching a view but reusing the existing element.
+   * Host Element. Most applications should use {@link DynamicComponentLoader#loadAsRoot} instead.
    *
-   * - `hostProtoViewRef`: {@link ProtoViewRef} Proto view to use in creating a view for this
+   * The Component and its View are created based on the `hostProtoViewRef` which can be obtained
-   *   component.
+   * by compiling the component with {@link Compiler#compileInHost}.
-   * - `overrideSelector`: (optional) selector to use in locating the existing element to load
-   *   the view into. If not specified use the selector in the component definition of the
-   *   `hostProtoView`.
-   * - injector: {@link Injector} to use as parent injector for the view.
    *
-   * See {@link AppViewManager#destroyRootHostView}.
+   * Use {@link AppViewManager#destroyRootHostView} to destroy the created Component and it's Host
+   * View.
    *
    * ## Example
    *
@@ -160,8 +153,12 @@ export class AppViewManager {
   }
 
   _destroyRootHostViewScope: WtfScopeFn = wtfCreateScope('AppViewManager#destroyRootHostView()');
+
   /**
-   * Remove the View created with {@link AppViewManager#createRootHostView}.
+   * Destroys the Host View created via {@link AppViewManager#createRootHostView}.
+   *
+   * Along with the Host View, the Component Instance as well as all nested View and Components are
+   * destroyed as well.
    */
   destroyRootHostView(hostViewRef: HostViewRef) {
     // Note: Don't put the hostView into the view pool
@@ -178,11 +175,20 @@ export class AppViewManager {
 
   _createEmbeddedViewInContainerScope: WtfScopeFn =
       wtfCreateScope('AppViewManager#createEmbeddedViewInContainer()');
+
   /**
-   * <!-- TODO: why "InContainer"? createRootHostView doesn't use this suffix. seems redundant -->
+   * Instantiates an Embedded View based on the {@link TemplateRef `templateRef`} and inserts it
+   * into the View Container specified via `viewContainerLocation` at the specified `index`.
    *
-   * See {@link AppViewManager#destroyViewInContainer}.
+   * Returns the {@link ViewRef} for the newly created View.
+   *
+   * This as a low-level way to create and attach an Embedded via to a View Container. Most
+   * applications should used {@link ViewContainerRef#createEmbeddedView} instead.
+   *
+   * Use {@link AppViewManager#destroyViewInContainer} to destroy the created Embedded View.
    */
+  // TODO(i): this low-level version of ViewContainerRef#createEmbeddedView doesn't add anything new
+  //    we should make it private, otherwise we have two apis to do the same thing.
   createEmbeddedViewInContainer(viewContainerLocation: ElementRef, index: number,
                                 templateRef: TemplateRef): ViewRef {
     var s = this._createEmbeddedViewInContainerScope();
@@ -196,10 +202,21 @@ export class AppViewManager {
 
   _createHostViewInContainerScope: WtfScopeFn =
       wtfCreateScope('AppViewManager#createHostViewInContainer()');
+
   /**
-   * <!-- TODO: why "InContainer"? createRootHostView doesn't use this suffix. seems redundant -->
+   * Instantiates a single {@link Component} and inserts its Host View into the View Container
+   * found at `viewContainerLocation`. Within the container, the view will be inserted at position
+   * specified via `index`.
    *
-   * See {@link AppViewManager#destroyViewInContainer}.
+   * The component is instantiated using its {@link ProtoViewRef `protoViewRef`} which can be
+   * obtained via {@link Compiler#compileInHost}.
+   *
+   * You can optionally specify `imperativelyCreatedInjector`, which configure the {@link Injector}
+   * that will be created for the Host View.
+   *
+   * Returns the {@link HostViewRef} of the Host View created for the newly instantiated Component.
+   *
+   * Use {@link AppViewManager#destroyViewInContainer} to destroy the created Host View.
    */
   createHostViewInContainer(viewContainerLocation: ElementRef, index: number,
                             protoViewRef: ProtoViewRef,
@@ -260,10 +277,11 @@ export class AppViewManager {
   }
 
   _destroyViewInContainerScope = wtfCreateScope('AppViewMananger#destroyViewInContainer()');
+
   /**
-   * <!-- TODO: why "InContainer"? createRootHostView doesn't use this suffix. seems redundant -->
+   * Destroys an Embedded or Host View attached to a View Container at the specified `index`.
    *
-   * See {@link AppViewManager#createViewInContainer}.
+   * The View Container is located via `viewContainerLocation`.
    */
   destroyViewInContainer(viewContainerLocation: ElementRef, index: number) {
     var s = this._destroyViewInContainerScope();
@@ -274,11 +292,12 @@ export class AppViewManager {
   }
 
   _attachViewInContainerScope = wtfCreateScope('AppViewMananger#attachViewInContainer()');
+
   /**
-   * <!-- TODO: why "InContainer"? createRootHostView doesn't use this suffix. seems redundant -->
    *
    * See {@link AppViewManager#detachViewInContainer}.
    */
+  // TODO(i): refactor detachViewInContainer+attachViewInContainer to moveViewInContainer
   attachViewInContainer(viewContainerLocation: ElementRef, index: number,
                         viewRef: ViewRef): ViewRef {
     var s = this._attachViewInContainerScope();
@@ -297,11 +316,11 @@ export class AppViewManager {
   }
 
   _detachViewInContainerScope = wtfCreateScope('AppViewMananger#detachViewInContainer()');
+
   /**
-   * <!-- TODO: why "InContainer"? createRootHostView doesn't use this suffix. seems redundant -->
-   *
    * See {@link AppViewManager#attachViewInContainer}.
    */
+  // TODO(i): refactor detachViewInContainer+attachViewInContainer to moveViewInContainer
   detachViewInContainer(viewContainerLocation: ElementRef, index: number): ViewRef {
     var s = this._detachViewInContainerScope();
     var parentView = internalView(viewContainerLocation.parentView);

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

@@ -130,8 +130,7 @@ export class AppViewManagerUtils {
     elementInjector.traverseAndSetQueriesAsDirty();
   }
 
-  detachViewInContainer(parentView: viewModule.AppView, boundElementIndex: number,
+  detachViewInContainer(parentView: viewModule.AppView, boundElementIndex: number, index: number) {
-                        index: number) {
     var viewContainer = parentView.viewContainers[boundElementIndex];
     var view = viewContainer.views[index];
 

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

@@ -13,8 +13,15 @@ export function internalProtoView(protoViewRef: ProtoViewRef): viewModule.AppPro
   return isPresent(protoViewRef) ? protoViewRef._protoView : null;
 }
 
+
 /**
- * Represents the View of a {@link Component} that was compiled via {@link Compiler#compileInHost
+ * Represents a View containing a single Element that is the Host Element of a {@link Component}
+ * instance.
+ *
+ * A Host View is created for every dynamically created Component that was compiled on its own (as
+ * opposed to as a part of another Component's Template) via {@link Compiler#compileInHost} or one
+ * of the higher-level APIs: {@link AppViewManager#createRootHostView},
+ * {@link AppViewManager#createHostViewInContainer}, {@link ViewContainerRef#createHostView}.
  */
 export interface HostViewRef {
   /**
@@ -31,8 +38,8 @@ export interface HostViewRef {
  * Elements which are created and destroyed together.
  *
  * Properties of elements in a View can change, but the structure (number and order) of elements in
- * a View cannot. Changing the structure of elements can only be done by inserting, moving or
+ * 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.
+ * removing nested Views via a {@link ViewContainer}. Each View can contain many View Containers.
  * <!-- /TODO -->
  *
  * ## Example
@@ -85,11 +92,15 @@ export class ViewRef implements HostViewRef {
   constructor(public _view: viewModule.AppView) {}
 
   /**
+   * @private
+   *
    * Return `RenderViewRef`
    */
   get render(): RenderViewRef { return this._view.render; }
 
   /**
+   * @private
+   *
    * Return `RenderFragmentRef`
    */
   get renderFragment(): RenderFragmentRef { return this._view.renderFragment; }
@@ -110,27 +121,25 @@ export class ViewRef implements HostViewRef {
   }
 
   /**
-   * Set local variable in a view.
+   * Sets `value` of local variable called `variableName` in this View.
-   *
-   * - `contextName` - Name of the local variable in a view.
-   * - `value` - Value for the local variable in a view.
    */
-  setLocal(contextName: string, value: any): void { this._view.setLocal(contextName, value); }
+  setLocal(variableName: string, value: any): void { this._view.setLocal(variableName, value); }
 }
 
 /**
- * Represents Angular's ProtoView.
+ * Represents an Angular ProtoView.
  *
- * A ProtoView is a prototypical View that is the result of Template compilation and enables
+ * A ProtoView is a prototypical {@link ViewRef View} that is the result of Template compilation and
- * Angular to efficiently create an instance of a View based on the compiled Template.
+ * is used by Angular to efficiently create an instance of this View based on the compiled Template.
  *
- * A ProtoView is created {@link AppViewManager#createViewInContainer} and
+ * Most ProtoViews are created and used internally by Angular and you don't need to know about them,
- * {@link AppViewManager#createRootHostView `AppViewManager#createRootHostView`}).
+ * except in advanced use-cases where you compile components yourself via the low-level
+ * {@link Compiler#compileInHost} API.
  *
  *
  * ## Example
  *
- * Given this template
+ * Given this template:
  *
  * ```
  * Count: {{items.length}}
@@ -139,9 +148,9 @@ export class ViewRef implements HostViewRef {
  * </ul>
  * ```
  *
- * The above example we have two {@link ProtoViewRef}s:
+ * Angular desugars and compiles the template into two ProtoViews:
  *
- * Outer {@link ProtoViewRef}:
+ * Outer ProtoView:
  * ```
  * Count: {{items.length}}
  * <ul>
@@ -149,12 +158,12 @@ export class ViewRef implements HostViewRef {
  * </ul>
  * ```
  *
- * Inner {@link ProtoViewRef}:
+ * Inner ProtoView:
  * ```
  *   <li>{{item}}</li>
  * ```
  *
- * Notice that the original template is broken down into two separate {@link ProtoViewRef}s.
+ * Notice that the original template is broken down into two separate ProtoViews.
  */
 export class ProtoViewRef {
   /**