docs: technical review incorporated (#24744)

closes #24744

packages/core/src/change_detection/change_detector_ref.ts

@@ -10,17 +10,17 @@
  * Base class for Angular Views, provides change detection functionality.
  * A change-detection tree collects all views that are to be checked for changes.
  * Use the methods to add and remove views from the tree, initiate change-detection,
- * and exlicitly mark views as _dirty_, meaning that they have changed and need to be rerendered.
+ * and explicitly mark views as _dirty_, meaning that they have changed and need to be rerendered.
  *
  * @usageNotes
  *
  * The following examples demonstrate how to modify default change-detection behavior
  * to perform explicit detection when needed.
  *
- * ### Use `markForCheck()` with `checkOnce` strategy
+ * ### Use `markForCheck()` with `CheckOnce` strategy
  *
  * The following example sets the `OnPush` change-detection strategy for a component
- * (`checkOnce`, rather than the default `checkAlways`), then forces a second check
+ * (`CheckOnce`, rather than the default `CheckAlways`), then forces a second check
  * after an interval. See [live demo](http://plnkr.co/edit/GC512b?p=preview).
  *
  * <code-example path="core/ts/change_detect/change-detection.ts"

packages/core/src/metadata/directives.ts

@@ -46,7 +46,7 @@ export interface DirectiveDecorator {
    * ### Declaring directives
    *
    * Directives are [declarables](guide/glossary#declarable).
-   * Like component and pipes, they must be declared by an NgModule
+   * They must be declared by an NgModule
    * in order to be usable in an app.
    *
    * A directive must belong to exactly one NgModule. Do not re-declare

packages/core/src/metadata/lifecycle_hooks.ts

@@ -100,9 +100,9 @@ export interface DoCheck {
   /**
      * A callback method that performs change-detection, invoked
      * after the default change-detector runs.
-     * @see `KeyValueDiffers` and `IterableDiffers` for implementing
+     * See `KeyValueDiffers` and `IterableDiffers` for implementing
      * custom change checking for collections.
-     * 
+     *
      */
   ngDoCheck(): void;
 }
@@ -115,7 +115,7 @@ export interface DoCheck {
  *
  * @usageNotes
  * The following snippet shows how a component can implement this interface
- * to define it own custom clean-up method.
+ * to define its own custom clean-up method.
  *  
  * {@example core/ts/metadata/lifecycle_hooks_spec.ts region='OnDestroy'}
  *

packages/core/src/metadata/ng_module.ts

@@ -211,19 +211,22 @@ export interface NgModule {
   declarations?: Array<Type<any>|any[]>;
 
   /**
-   * The set of NgModules whose exported directives and pipes
+   * The set of NgModules whose exported [declarables](guide/glossary#declarable)
    * are available to templates in this module.
    *
    * @usageNotes
    *
-   * A template can exported declarables from any
-   * imported module, including those that are imported indirectly.
-   * For example, `CommonModule` imports `BrowserModule`, make the
-   * `BrowserModule` exports available wherever `CommonModule` is imported.
+   * A template can use exported declarables from any
+   * imported module, including those from modules that are imported indirectly
+   * and re-exported.
+   * For example, `ModuleA` imports `ModuleB`, and also exports
+   * it, which makes the declarables from `ModuleB` available
+   * wherever `ModuleA` is imported.
    *
    * ### Example
    *
-   * The following example allows MainModule to use `CommonModule`:
+   * The following example allows MainModule to use anthing exported by
+   * `CommonModule`:
    *
    * ```javascript
    * @NgModule({
@@ -241,19 +244,18 @@ export interface NgModule {
    * NgModule that can be used in the template of any component that is part of an
    * NgModule that imports this NgModule. Exported declarations are the module's public API.
    *
+   * A declarable belongs to one and only one NgModule.
+   * A module can list another module among its exports, in which case all of that module's
+   * public declaration are exported.
+   *
    * @usageNotes
    *
-   * Declarations are private by default. If this module does not export UserComponent,
-   * then only the components within this module can use UserComponent.
+   * Declarations are private by default.
+   * If this ModuleA does not export UserComponent, then only the components within this
+   * ModuleA can use UserComponent.
    *
-   * Importing a module does not automatically re-export the imported module's imports.
-   * Module 'B' can't use `ngIf` just because it imported module 'A' which imported `CommonModule`.
-   * Module 'B' must import `CommonModule` itself.
-   *
-   * A module can list another module among its exports, in which case all of that module's
-   * public declaration are exported. Re-export makes module transitivity explicit.
-   * If Module 'A' re-exports `CommonModule` and Module 'B' imports Module 'A',
-   * then Module 'B' components can use `ngIf` even though 'B' itself did not import `CommonModule`.
+   * ModuleA can import ModuleB and also export it, making exports from ModuleB
+   * available to an NgModule that imports ModuleA.
    *
    * ### Example
    *
@@ -279,7 +281,7 @@ export interface NgModule {
    * Angular automatically adds components in the module's bootstrap
    * and route definitions into the `entryComponents` list. Use this
    * option to add components that are bootstrapped
-   * using one of the imperative techniques, such as `ViewComponentRef.createComponent()`.
+   * using one of the imperative techniques, such as `ViewContainerRef.createComponent()`.
    *
    * @see [Entry Components](guide/entry-components)
    */
@@ -346,7 +348,7 @@ export const NgModule: NgModuleDecorator = makeDecorator(
      * with information about what belongs to the NgModule.
      * * The `providers` options configures the NgModule's injector to provide
      * dependencies the NgModule members.
-     * * The `import` and `export` options bring in members from other modules, and make
+     * * The `imports` and `exports` options bring in members from other modules, and make
      * this module's members available to others.
      */
     (type: Type<any>, meta: NgModule) => (R3_COMPILE_NGMODULE || preR3NgModuleCompile)(type, meta));

packages/core/src/render/api.ts

@@ -128,7 +128,7 @@ export interface RendererType2 {
    * DOM elements. One of
    * - `Emulated` (default): Emulate native scoping of styles.
    * - `Native`: Use the native encapsulation mechanism of the renderer.
-   * - `ShadowDoc`: Use modern [Shadow
+   * - `ShadowDom`: Use modern [Shadow
    * DOM](https://w3c.github.io/webcomponents/spec/shadow/) and
    * create a ShadowRoot for component's host element.
    * - `None`: Do not provide any template or style encapsulation.
@@ -152,7 +152,7 @@ export interface RendererType2 {
  */
 export abstract class RendererFactory2 {
   /**
-   * Implements a custom renderer for a host DOM element.
+   * Creates and initializes a custom renderer for a host DOM element.
    * @param hostElement The element to render.
    * @param type The base class to implement.
    * @returns The new custom renderer instance.
@@ -195,17 +195,17 @@ export enum RendererStyleFlags2 {
  *
  * Create your custom renderer using `RendererFactory2`.
  *
- * Use a custom renderer to bypass Angular's templating and make custom UI changes that can't be
- * expressed declaratively.
+ * Use a custom renderer to bypass Angular's templating and
+ * make custom UI changes that can't be expressed declaratively.
  * For example if you need to set a property or an attribute whose name is
- * not statically known, use the `setElementProperty()` or
- * `setElementAttribute()` method.
+ * not statically known, use the `setProperty()` or
+ * `setAttribute()` method.
  *
  * @experimental
  */
 export abstract class Renderer2 {
   /**
-   * Implement this callback to store arbitrary developer-defined data on a renderer instance,
+   * Use to store arbitrary developer-defined data on a renderer instance,
    * as an object containing key-value pairs.
    * This is useful for renderers that delegate to other renderers.
    */
@@ -262,7 +262,8 @@ export abstract class Renderer2 {
    */
   abstract removeChild(parent: any, oldChild: any): void;
   /**
-   * Implement this callback to get the root element of a DOM element.
+   * Implement this callback to prepare an element to be bootstrapped
+   * as a root element, and return the element instance.
    * @param selectorOrNode The DOM element.
    * @returns The root element.
    */
@@ -355,6 +356,7 @@ export abstract class Renderer2 {
    * DOM element.
    * @param eventName The event to listen for.
    * @param callback A handler function to invoke when the event occurs.
+   * @returns An "unlisten" function for disposing of this handler.
    */
   abstract listen(
       target: 'window'|'document'|'body'|any, eventName: string,