From bc7f962039dce12358e97846a9883271e9d04e74 Mon Sep 17 00:00:00 2001 From: Judy Bogart Date: Tue, 11 Sep 2018 12:09:09 -0700 Subject: [PATCH] docs: clean up formats, add detail (#25582) PR Close #25582 --- packages/core/src/linker/template_ref.ts | 34 ++++++++++++------- .../core/src/linker/view_container_ref.ts | 9 ++++- packages/core/src/linker/view_ref.ts | 8 +++++ 3 files changed, 38 insertions(+), 13 deletions(-) diff --git a/packages/core/src/linker/template_ref.ts b/packages/core/src/linker/template_ref.ts index d3fc094d5b..3013ea8fa6 100644 --- a/packages/core/src/linker/template_ref.ts +++ b/packages/core/src/linker/template_ref.ts @@ -11,31 +11,41 @@ import {EmbeddedViewRef} from './view_ref'; /** - * Represents an Embedded Template that can be used to instantiate Embedded Views. + * Represents an embedded template that can be used to instantiate embedded views. + * To instantiate embedded views based on a template, use {@link ViewContainerRef# + * createEmbeddedView}. + * + * Access a `TemplateRef` instance by placing a directive (or directive prefixed with `*`) + * on an `` element. The `TemplateRef` for the embedded view + * is injected into the constructor of the directive, + * using the `TemplateRef` token. + * + * You can also use a `Query` to find a `TemplateRef` associated with + * a component or a directive. * - * You can access a `TemplateRef`, in two ways. Via a directive placed on a `` 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}. - * - * To instantiate Embedded Views based on a Template, use {@link ViewContainerRef# - * createEmbeddedView}, which will create the View and attach it to the View Container. + * @see `ViewContainerRef` + * @see [Navigate the Component Tree with DI](guide/dependency-injection-navtree) * */ export abstract class TemplateRef { /** - * The location in the View where the Embedded View logically belongs to. + * The anchor element in the parent view for this embedded view. * - * The data-binding and injection contexts of Embedded Views created from this `TemplateRef` + * 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 + * 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. * */ // TODO(i): rename to anchor or location abstract get elementRef(): ElementRef; + /** + * Creates a view object and attaches it to the view container of the parent view. + * @param context The context for the new view, inherited from the anchor element. + * @returns The new view object. + */ abstract createEmbeddedView(context: C): EmbeddedViewRef; } diff --git a/packages/core/src/linker/view_container_ref.ts b/packages/core/src/linker/view_container_ref.ts index 132d153c74..798bdf4be8 100644 --- a/packages/core/src/linker/view_container_ref.ts +++ b/packages/core/src/linker/view_container_ref.ts @@ -16,10 +16,17 @@ import {EmbeddedViewRef, ViewRef} from './view_ref'; /** * 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_ + * component with the `createComponent()` method), and _embedded views_ * (created by instantiating a `TemplateRef` with the `createEmbeddedView()` method. * + * A view container instance can contain other view containers, + * creating a [view hierarchy](guide/glossary#view-tree). + * + * @see `ComponentRef` + * @see `EmbeddedViewRef` + * */ export abstract class ViewContainerRef { /** diff --git a/packages/core/src/linker/view_ref.ts b/packages/core/src/linker/view_ref.ts index 815f6db806..586eef47c1 100644 --- a/packages/core/src/linker/view_ref.ts +++ b/packages/core/src/linker/view_ref.ts @@ -50,6 +50,8 @@ export abstract class ViewRef extends ChangeDetectorRef { * * @see `ViewContainerRef` * + * @usageNotes + * * The following template breaks down into two separate `TemplateRef` instances, * an outer one and and an inner one. * @@ -90,8 +92,14 @@ export abstract class ViewRef extends ChangeDetectorRef { * @experimental */ export abstract class EmbeddedViewRef extends ViewRef { + /** + * The context for this view, inherited from the anchor element. + */ abstract get context(): C; + /** + * The root nodes for this embedded view. + */ abstract get rootNodes(): any[]; }