From 78d42a9503e1e05ba3e52d5406e66165914e2070 Mon Sep 17 00:00:00 2001 From: Judy Bogart Date: Mon, 20 Aug 2018 14:32:11 -0700 Subject: [PATCH] docs: update view-related api doc (#25582) PR Close #25582 --- .../change_detection/change_detector_ref.ts | 2 +- packages/core/src/linker/component_factory.ts | 36 +++--- .../core/src/linker/view_container_ref.ts | 104 ++++++++++-------- packages/core/src/linker/view_ref.ts | 52 +++++---- 4 files changed, 112 insertions(+), 82 deletions(-) diff --git a/packages/core/src/change_detection/change_detector_ref.ts b/packages/core/src/change_detection/change_detector_ref.ts index 49cdaf425d..4090d09ef6 100644 --- a/packages/core/src/change_detection/change_detector_ref.ts +++ b/packages/core/src/change_detection/change_detector_ref.ts @@ -44,7 +44,7 @@ * when the `live` property is set to false, and reattaches it when the property * becomes true. * - * + * * */ export abstract class ChangeDetectorRef { diff --git a/packages/core/src/linker/component_factory.ts b/packages/core/src/linker/component_factory.ts index 096a89b4f7..9a6692c5da 100644 --- a/packages/core/src/linker/component_factory.ts +++ b/packages/core/src/linker/component_factory.ts @@ -15,36 +15,35 @@ import {NgModuleRef} from './ng_module_factory'; import {ViewRef} from './view_ref'; /** - * Represents an instance of a Component created via a {@link ComponentFactory}. - * - * `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 #destroy} - * method. + * Represents a component created by a `ComponentFactory`. + * Provides access to the component instance and related objects, + * and provides the means of destroying the instance. * */ export abstract class ComponentRef { /** - * Location of the Host Element of this Component Instance. + * The host or anchor [element](guide/glossary#element) for this component instance. */ abstract get location(): ElementRef; /** - * The injector on which the component instance exists. + * The [dependency injector](guide/glossary#injector) for this component instance. */ abstract get injector(): Injector; /** - * The instance of the Component. + * This component instance. */ abstract get instance(): C; /** - * The {@link ViewRef} of the Host View of this Component instance. + * The [host view](guide/glossary#view-tree) defined by the template + * for this component instance. */ abstract get hostView(): ViewRef; /** - * The {@link ChangeDetectorRef} of the Component instance. + * The change detector for this component instance. */ abstract get changeDetectorRef(): ChangeDetectorRef; @@ -59,24 +58,33 @@ export abstract class ComponentRef { abstract destroy(): void; /** - * Allows to register a callback that will be called when the component is destroyed. + * A lifecycle hook that provides additional developer-defined cleanup + * functionality for the component. + * @param callback A handler function that cleans up developer-defined data + * associated with this component. Called when the `destroy()` method is invoked. */ abstract onDestroy(callback: Function): void; } export abstract class ComponentFactory { + /** + * The comonent's HTML selector. + */ abstract get selector(): string; + /** + * The component's type + */ abstract get componentType(): Type; /** - * selector for all elements in the component. + * Selector for all elements in the component. */ abstract get ngContentSelectors(): string[]; /** - * the inputs of the component. + * The inputs of the component. */ abstract get inputs(): {propName: string, templateName: string}[]; /** - * the outputs of the component. + * The outputs of the component. */ abstract get outputs(): {propName: string, templateName: string}[]; /** diff --git a/packages/core/src/linker/view_container_ref.ts b/packages/core/src/linker/view_container_ref.ts index bd2917fcec..132d153c74 100644 --- a/packages/core/src/linker/view_container_ref.ts +++ b/packages/core/src/linker/view_container_ref.ts @@ -15,111 +15,121 @@ import {EmbeddedViewRef, ViewRef} 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 #createComponent}, 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 a {@link ViewChild} query. + * Represents a container where one or more views can be attached to a component. + * Can contain _host_ views (created by instantiating a + * Component` with the `createComponent()` method), and _embedded views_ + * (created by instantiating a `TemplateRef` with the `createEmbeddedView()` method. * */ export abstract class ViewContainerRef { /** - * Anchor element that specifies the location of this container in the containing View. + * Anchor element that specifies the location of this container in the containing view. + * Each view container can have only one anchor element, and each anchor element + * can have only a single view container. + * + * Root elements of views attached to this container become siblings of the anchor element in + * the rendered view. + * + * Access the `ViewContainerRef` of an element by placing a `Directive` injected + * with `ViewContainerRef` on the element, or use a `ViewChild` query. + * * */ abstract get element(): ElementRef; + /** + * The [dependency injector](guide/glossary#injector) for this view container. + */ abstract get injector(): Injector; /** @deprecated No replacement */ abstract get parentInjector(): Injector; /** - * Destroys all Views in this container. + * Destroys all views in this container. */ abstract clear(): void; /** - * Returns the {@link ViewRef} for the View located in this container at the specified index. + * Retrieves a view from this container. + * @param index The 0-based index of the view to retrieve. + * @returns The `ViewRef` instance, or null if the index is out of range. */ abstract get(index: number): ViewRef|null; /** - * Returns the number of Views currently attached to this container. + * Reports how many views are currently attached to this container. + * @returns The number of views. */ abstract get length(): number; /** - * Instantiates an Embedded View based on the {@link TemplateRef `templateRef`} and inserts it - * into this container at the specified `index`. + * Instantiates an embedded view and inserts it + * into this container. + * @param templateRef The HTML template that defines the view. + * @param index The 0-based index at which to insert the new view into this container. + * If not specified, appends the new view as the last entry. * - * If `index` is not specified, the new View will be inserted as the last View in the container. - * - * Returns the {@link ViewRef} for the newly created View. + * @returns The `ViewRef` instance for the newly created view. */ abstract createEmbeddedView(templateRef: TemplateRef, context?: C, index?: number): EmbeddedViewRef; /** - * Instantiates a single {@link Component} and inserts its Host View into this container at the - * specified `index`. + * Instantiates a single component and inserts its host view into this container. * - * The component is instantiated using its {@link ComponentFactory} which can be obtained via - * {@link ComponentFactoryResolver#resolveComponentFactory resolveComponentFactory}. + * @param componentFactory The factory to use. + * @param index The index at which to insert the new component's host view into this container. + * If not specified, appends the new view as the last entry. + * @param injector The injector to use as the parent for the new component. + * @param projectableNodes + * @param ngModule * - * If `index` is not specified, the new View will be inserted as the last View in the container. + * @returns The new component instance, containing the host view. * - * You can optionally specify the {@link Injector} that will be used as parent for the Component. - * - * Returns the {@link ComponentRef} of the Host View created for the newly instantiated Component. */ abstract createComponent( componentFactory: ComponentFactory, index?: number, injector?: Injector, projectableNodes?: any[][], ngModule?: NgModuleRef): ComponentRef; /** - * Inserts a View identified by a {@link ViewRef} into the container at the specified `index`. + * Inserts a view into this container. + * @param viewRef The view to insert. + * @param index The 0-based index at which to insert the view. + * If not specified, appends the new view as the last entry. + * @returns The inserted `ViewRef` instance. * - * If `index` is not specified, the new View will be inserted as the last View in the container. - * - * Returns the inserted {@link ViewRef}. */ abstract insert(viewRef: ViewRef, index?: number): ViewRef; /** - * Moves a View identified by a {@link ViewRef} into the container at the specified `index`. - * - * Returns the inserted {@link ViewRef}. + * Moves a view to a new location in this container. + * @param viewRef The view to move. + * @param index The 0-based index of the new location. + * @returns The moved `ViewRef` instance. */ abstract move(viewRef: ViewRef, currentIndex: number): ViewRef; /** - * Returns the index of the View, specified via {@link ViewRef}, within the current container or - * `-1` if this container doesn't contain the View. + * Returns the index of a view within the current container. + * @parem viewRef The view to query. + * @returns The 0-based index of the view's position in this container, + * or `-1` if this container doesn't contain the view. */ abstract indexOf(viewRef: ViewRef): number; /** - * 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. + * Destroys a view attached to this container + * @param index The 0-based index of the view to destroy. + * If not specified, the last view in the container is removed. */ abstract remove(index?: number): void; /** - * 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. + * Detaches a view from this container without destroying it. + * Use along with `insert()` to move a view within the current container. + * @param index The 0-based index of the view to detach. + * If not specified, the last view in the container is detached. */ abstract detach(index?: number): ViewRef|null; } diff --git a/packages/core/src/linker/view_ref.ts b/packages/core/src/linker/view_ref.ts index ffeb9be846..815f6db806 100644 --- a/packages/core/src/linker/view_ref.ts +++ b/packages/core/src/linker/view_ref.ts @@ -9,33 +9,49 @@ import {ApplicationRef} from '../application_ref'; import {ChangeDetectorRef} from '../change_detection/change_detector_ref'; +/** + * Represents an Angular [view](guide/glossary#view), + * specifically the [host view](guide/glossary#view-tree) that is defined by a component. + * Also serves as the base class + * that adds destroy methods for [embedded views](guide/glossary#view-tree). + * + * @see `EmbeddedViewRef` + */ export abstract class ViewRef extends ChangeDetectorRef { /** - * Destroys the view and all of the data structures associated with it. + * Destroys this view and all of the data structures associated with it. */ abstract destroy(): void; + /** + * Reports whether this view has been destroyed. + * @returns True after the `destroy()` method has been called, false otherwise. + */ abstract get destroyed(): boolean; + /** + * A lifecycle hook that provides additional developer-defined cleanup + * functionality for views. + * @param callback A handler function that cleans up developer-defined data + * associated with a view. Called when the `destroy()` method is invoked. + */ abstract onDestroy(callback: Function): any /** TODO #9100 */; } /** - * Represents an Angular View. + * Represents an Angular [view](guide/glossary#view) in a view container. + * An [embedded view](guide/glossary#view-tree) can be referenced from a component + * other than the hosting component whose template defines it, or it can be defined + * independently by a `TemplateRef`. * - * - * A View is a fundamental building block of the application UI. It is the smallest grouping of - * 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. Change the structure of elements by inserting, moving, or + * removing nested views in a view container. * - * 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 - * removing nested Views via a `ViewContainerRef`. Each View can contain many View Containers. - * + * @see `ViewContainerRef` * - * @usageNotes - * ### Example - * - * Given this template... + * The following template breaks down into two separate `TemplateRef` instances, + * an outer one and and an inner one. * * ``` * Count: {{items.length}} @@ -44,9 +60,7 @@ export abstract class ViewRef extends ChangeDetectorRef { * * ``` * - * We have two `TemplateRef`s: - * - * Outer `TemplateRef`: + * This is the outer `TemplateRef`: * * ``` * Count: {{items.length}} @@ -55,15 +69,13 @@ export abstract class ViewRef extends ChangeDetectorRef { * * ``` * - * Inner `TemplateRef`: + * This is the inner `TemplateRef`: * * ``` *
  • {{item}}
    • * ``` * - * Notice that the original template is broken down into two separate `TemplateRef`s. - * - * The outer/inner `TemplateRef`s are then assembled into views like so: + * The outer and inner `TemplateRef` instances are assembled into views as follows: * * ``` *