docs(compiler): compiler/view related api docs

Closes angular#4268

Author: IgorMinar

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
- * {@link View}s can be rendered.
+ * Low-level service for compiling {@link Component}s into {@link ProtoViewRef ProtoViews}s, which
+ * 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
-   * {@link ProtoViewRef} that can be passed into {@link AppViewManager
+   * Compiles a {@link Component} and returns a promise for this component's {@link ProtoViewRef}.
+   *
+   * 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
- * other objects related to this component instance.
+ * Represents an instance of a Component created via {@link DynamicComponentLoader}.
+ *
+ * `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
- * application at a specified location.
+ * Service for instantiating a Component and attaching it to a View 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
-   * selector.
+   * Creates an instance of a Component `type` and attaches it to the first element in the
+   * platform-specific global view that matches the component's selector.
+   *
+   * In a browser the platform-specific global view is the main DOM Document.
    *
-   * - `typeOrBinding` `Type` - representing the component to load.
-   * - `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.
+   * If needed, the component's selector can be overridden via `overrideSelector`.
    *
-   * The loaded component receives injection normally as a hosted view.
+   * 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
-   * with the given name.
+   * Creates an instance of a Component and attaches it to a View Container located inside of the
+   * 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}.
+   *
+   * You can optionally provide `bindings` to configure the {@link Injector} provisioned for this
+   * Component Instance.
    *
-   * The loaded component receives injection normally as a hosted view.
+   * 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
- * DOM element.
+ * An `ElementRef` is backed by a render-specific element. In the browser, this is usually a DOM
+ * 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
- * it to a View Container.
+ * You can access a `TemplateRef`, in two ways. Via a directive placed on a `<template>` element (or
+ * 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
-   * Embedded View is instatiated.
+   * @private
+   *
+   * 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); }
 }