docs(compiler): compiler related api docs

Author: IgorMinar

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.
- *
- * `ComponentRef` represents a component instance lifecycle and meta information.
+ * Represents a component instance as a node in application's component tree and provides access to
+ * other objects related to this component instance.
  */
 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
- * application tree.
+ * Service for creating an instance of a component and attaching it to the component tree of an
+ * 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,33 +3,46 @@ 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
- * types on other rendering platforms. In the browser the `ElementRef` can be sent to the Web
- * Worker. Web Workers can not have references to the DOM Elements.
+ * 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.
  */
 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.
  */
  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.
- *
- * In the browser this represents the DOM element.
- *
- * The `nativeElement` can be used as an escape hatch when direct DOM manipulation is needed. Use
- * this with caution, as it creates tight coupling between your application and the browser, which
- * will not work in Web Workers.
+ * 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).
  *
- * NOTE: This method will return null in the webworker scenario!
+ * <div class="callout is-critical">
+ * <header>Use with caution</header>
+ * <p>
+ * Use this api as the last resort when direct access to DOM is needed. Use templating and
+ * data-binding provided by Angular instead.
+ * </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
+ * 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
- * be instantiated using the {@link ViewContainerRef}.
+ * Use {@link ViewContainerRef#createEmbeddedView} method to instantiate an Embedded View and attach
+ * 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,25 +10,52 @@ 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
- * {@link ViewRef}s can be inserted. Adding and removing views is the only way of structurally
- * changing the rendered DOM of the application.
+ * 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 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];
  return isPresent(vc) ? vc.views : [];
  }
 
  /**
- * 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
- * `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`.
+ * If `atIndex` is not specified, the new View will be inserted as the last View in the container.
  *
- * 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,29 +110,32 @@ 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
- * inserted at the end.
+ * If `atIndex` 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 -->
  */
  insert(viewRef: ViewRef, atIndex: number = -1): ViewRef {
  if (atIndex == -1) atIndex = this.length;
  return this.viewManager.attachViewInContainer(this.element, atIndex, viewRef);
  }
 
  /**
- * 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.
- * moving the DOM nodes while the directives in the view stay intact.
+ * <!-- TODO: refactor into move and remove -->
+ * 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;