From bc7f962039dce12358e97846a9883271e9d04e74 Mon Sep 17 00:00:00 2001
From: Judy Bogart <jbogart@gmail.com>
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 `<ng-template>` 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 `<ng-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}.
- *
- * 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<C> {
   /**
-   * 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<C>;
 }
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<C> 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[];
 }