docs: update view-related api doc (#25582)

PR Close #25582

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.
  *
- * <code-example path="core/ts/change_detect/change-detection.ts" region="detach"></code-example>
+ * <code-example path="core/ts/change_detect/change-detection.ts" region="reattach"></code-example>
  *
  */
 export abstract class ChangeDetectorRef {

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}.
+ * Represents a component created by a `ComponentFactory`.
- *
+ * Provides access to the component instance and related objects,
- * `ComponentRef` provides access to the Component Instance as well other objects related to this
+ * and provides the means of destroying the instance.
- * Component Instance and allows you to destroy the Component Instance via the {@link #destroy}
- * method.
  *
  */
 export abstract class ComponentRef<C> {
   /**
-   * 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<C> {
   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<C> {
+  /**
+   * The comonent's HTML selector.
+   */
   abstract get selector(): string;
+  /**
+   * The component's type
+   */
   abstract get componentType(): Type<any>;
   /**
-   * selector for all <ng-content> elements in the component.
+   * Selector for all <ng-content> 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}[];
   /**

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.
+ * Represents a container where one or more views can be attached to a component.
- *
+ * Can contain _host_ views (created by instantiating a
- * The container can contain two kinds of Views. Host Views, created by instantiating a
+ * Component` with the `createComponent()` method), and _embedded views_
- * {@link Component} via {@link #createComponent}, and Embedded Views, created by instantiating an
+ * (created by instantiating a `TemplateRef` with the `createEmbeddedView()` method.
- * {@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.
  *
  */
 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.
+   *
    * <!-- TODO: rename to anchorElement -->
    */
   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
+   * Instantiates an embedded view and inserts it
-   * into this container at the specified `index`.
+   * 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 `ViewRef` instance for the newly created view.
-   *
-   * Returns the {@link ViewRef} for the newly created View.
    */
   abstract createEmbeddedView<C>(templateRef: TemplateRef<C>, context?: C, index?: number):
       EmbeddedViewRef<C>;
 
   /**
-   * Instantiates a single {@link Component} and inserts its Host View into this container at the
+   * Instantiates a single component and inserts its host view into this container.
-   * specified `index`.
    *
-   * The component is instantiated using its {@link ComponentFactory} which can be obtained via
+   * @param componentFactory The factory to use.
-   * {@link ComponentFactoryResolver#resolveComponentFactory resolveComponentFactory}.
+   * @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<C>(
       componentFactory: ComponentFactory<C>, index?: number, injector?: Injector,
       projectableNodes?: any[][], ngModule?: NgModuleRef<any>): ComponentRef<C>;
 
   /**
-   * 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`.
+   * Moves a view to a new location in this container.
-   *
+   * @param viewRef The view to move.
-   * Returns the inserted {@link ViewRef}.
+   * @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
+   * Returns the index of a view within the current container.
-   * `-1` if this container doesn't contain the View.
+   * @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`.
+   * Destroys a view attached to this container
-   *
+   * @param index The 0-based index of the view to destroy.
-   * If `index` is not specified, the last View in the container will be removed.
+   * 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.
+   * Detaches a view from this container without destroying it.
-   *
+   * Use along with `insert()` to move a view within the current container.
-   * If the `index` param is omitted, the last {@link ViewRef} is detached.
+   * @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;
 }

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`.
  *
- * <!-- TODO: move the next two paragraphs to the dev guide -->
+ * Properties of elements in a view can change, but the structure (number and order) of elements in
- * A View is a fundamental building block of the application UI. It is the smallest grouping of
+ * a view cannot. Change the structure of elements by inserting, moving, or
- * Elements which are created and destroyed together.
+ * removing nested views in a view container.
  *
- * Properties of elements in a View can change, but the structure (number and order) of elements in
+ * @see `ViewContainerRef`
- * 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.
- * <!-- /TODO -->
  *
- * @usageNotes
+ * The following template breaks down into two separate `TemplateRef` instances,
- * ### Example
+ * an outer one and and an inner one.
- *
- * Given this template...
  *
  * ```
  * Count: {{items.length}}
@@ -44,9 +60,7 @@ export abstract class ViewRef extends ChangeDetectorRef {
  * </ul>
  * ```
  *
- * We have two `TemplateRef`s:
+ * This is the outer `TemplateRef`:
- *
- * Outer `TemplateRef`:
  *
  * ```
  * Count: {{items.length}}
@@ -55,15 +69,13 @@ export abstract class ViewRef extends ChangeDetectorRef {
  * </ul>
  * ```
  *
- * Inner `TemplateRef`:
+ * This is the inner `TemplateRef`:
  *
  * ```
  *   <li>{{item}}</li>
  * ```
  *
- * Notice that the original template is broken down into two separate `TemplateRef`s.
+ * The outer and inner `TemplateRef` instances are assembled into views as follows:
- *
- * The outer/inner `TemplateRef`s are then assembled into views like so:
  *
  * ```
  * <!-- ViewRef: outer-0 -->