From 7960d1879d87f1d9e4f7f202423960d874a6a08f Mon Sep 17 00:00:00 2001 From: Judy Bogart Date: Wed, 18 Jul 2018 10:26:59 -0700 Subject: [PATCH] docs: technical review incorporated (#24744) closes #24744 --- .../change_detection/change_detector_ref.ts | 6 +-- packages/core/src/metadata/directives.ts | 2 +- packages/core/src/metadata/lifecycle_hooks.ts | 6 +-- packages/core/src/metadata/ng_module.ts | 38 ++++++++++--------- packages/core/src/render/api.ts | 18 +++++---- 5 files changed, 37 insertions(+), 33 deletions(-) diff --git a/packages/core/src/change_detection/change_detector_ref.ts b/packages/core/src/change_detection/change_detector_ref.ts index ffe982f003..49cdaf425d 100644 --- a/packages/core/src/change_detection/change_detector_ref.ts +++ b/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). * * |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, meta: NgModule) => (R3_COMPILE_NGMODULE || preR3NgModuleCompile)(type, meta)); diff --git a/packages/core/src/render/api.ts b/packages/core/src/render/api.ts index b3b281bb3f..ab442b419b 100644 --- a/packages/core/src/render/api.ts +++ b/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,