From dd5e35ee67b5d77199e011f921a394b6479e7302 Mon Sep 17 00:00:00 2001 From: Judy Bogart Date: Wed, 22 Aug 2018 08:52:19 -0700 Subject: [PATCH] docs: add ngmodule api doc (#25618) PR Close #25618 --- packages/common/http/src/module.ts | 21 ++++++++++++------- packages/common/src/common_module.ts | 9 +++++++- packages/core/src/application_module.ts | 12 +++++++++-- packages/forms/src/form_providers.ts | 10 +++++---- .../platform-browser/animations/src/module.ts | 7 +++++-- packages/platform-browser/src/browser.ts | 15 +++++++++---- 6 files changed, 53 insertions(+), 21 deletions(-) diff --git a/packages/common/http/src/module.ts b/packages/common/http/src/module.ts index be0a79fb54..ff06059d2f 100644 --- a/packages/common/http/src/module.ts +++ b/packages/common/http/src/module.ts @@ -76,7 +76,7 @@ export function jsonpCallbackContext(): Object { } /** - * An NgModule that adds XSRF protection support to outgoing requests. + * Configures XSRF protection support for outgoing requests. * * For a server that supports a cookie-based XSRF protection system, * use directly to configure XSRF protection with the correct @@ -132,10 +132,11 @@ export class HttpClientXsrfModule { } /** - * An NgModule that provides the `HttpClient` and associated services. + * Configures the [dependency injector](guide/glossary#injector) for `HttpClient` + * with supporting services for XSRF. Automatically imported by `HttpClientModule`. * - * Interceptors can be added to the chain behind `HttpClient` by binding them - * to the multiprovider for `HTTP_INTERCEPTORS`. + * You can add interceptors to the chain behind `HttpClient` by binding them to the + * multiprovider for built-in [DI token](guide/glossary#di-token) `HTTP_INTERCEPTORS`. * * */ @@ -150,7 +151,8 @@ export class HttpClientXsrfModule { }), ], /** - * The module provides `HttpClient` itself, and supporting services. + * Configures the [dependency injector](guide/glossary#injector) where it is imported + * with supporting services for HTTP communications. */ providers: [ HttpClient, @@ -165,10 +167,13 @@ export class HttpClientModule { } /** - * An NgModule that enables JSONP support in `HttpClient`. + * Configures the [dependency injector](guide/glossary#injector) for `HttpClient` + * with supporting services for JSONP. + * Without this module, Jsonp requests reach the backend + * with method JSONP, where they are rejected. * - * Without this module, Jsonp requests will reach the backend - * with method JSONP, where they'll be rejected. + * You can add interceptors to the chain behind `HttpClient` by binding them to the + * multiprovider for built-in [DI token](guide/glossary#di-token) `HTTP_INTERCEPTORS`. * * */ diff --git a/packages/common/src/common_module.ts b/packages/common/src/common_module.ts index 07c1557836..4dda41c007 100644 --- a/packages/common/src/common_module.ts +++ b/packages/common/src/common_module.ts @@ -16,8 +16,15 @@ import {COMMON_PIPES} from './pipes/index'; // Note: This does not contain the location providers, // as they need some platform specific implementations to work. /** - * The module that includes all the basic Angular directives like {@link NgIf}, {@link NgForOf}, ... + * Exports all the basic Angular directives and pipes, + * such as `NgIf`, `NgForOf`, `DecimalPipe`, and so on. + * Re-exported by `BrowserModule`, which is included automatically in the root + * `AppModule` when you create a new app with the CLI `new` command. * + * * The `providers` options configure the NgModule's injector to provide + * localization dependencies to members. + * * The `exports` options make the declared directives and pipes available for import + * by other NgModules. * */ @NgModule({ diff --git a/packages/core/src/application_module.ts b/packages/core/src/application_module.ts index 4cbd10b24b..8d9d32de63 100644 --- a/packages/core/src/application_module.ts +++ b/packages/core/src/application_module.ts @@ -32,6 +32,10 @@ export function _localeFactory(locale?: string): string { return locale || 'en-US'; } +/** + * A built-in [dependency injection token](guide/glossary#di-token) + * that is used to configure the root injector for bootstrapping. + */ export const APPLICATION_MODULE_PROVIDERS: StaticProvider[] = [ { provide: ApplicationRef, @@ -56,8 +60,12 @@ export const APPLICATION_MODULE_PROVIDERS: StaticProvider[] = [ ]; /** - * This module includes the providers of @angular/core that are needed - * to bootstrap components via `ApplicationRef`. + * Configures the root injector for an app with + * providers of `@angular/core` dependencies that `ApplicationRef` needs + * to bootstrap components. + * + * Re-exported by `BrowserModule`, which is included automatically in the root + * `AppModule` when you create a new app with the CLI `new` command. * * @experimental */ diff --git a/packages/forms/src/form_providers.ts b/packages/forms/src/form_providers.ts index 60db1042cf..56f7f42bf9 100644 --- a/packages/forms/src/form_providers.ts +++ b/packages/forms/src/form_providers.ts @@ -13,8 +13,9 @@ import {RadioControlRegistry} from './directives/radio_control_value_accessor'; import {FormBuilder} from './form_builder'; /** - * @description - * An `NgModule` that registers the directives and providers for template-driven forms. + * Exports the required providers and directives for template-driven forms, + * making them available for import by NgModules that import this module. + * @see [Forms](guide/forms) * * @see [Forms Guide](/guide/forms) */ @@ -44,8 +45,9 @@ export class FormsModule { } /** - * @description - * An `NgModule` that registers the directives and providers for reactive forms. + * Exports the required infrastructure and directives for reactive forms, + * making them available for import by NgModules that import this module. + * @see [Forms](guide/reactive-forms) * * @see [Reactive Forms Guide](/guide/reactive-forms) * diff --git a/packages/platform-browser/animations/src/module.ts b/packages/platform-browser/animations/src/module.ts index 39ad025556..c8d23224c3 100644 --- a/packages/platform-browser/animations/src/module.ts +++ b/packages/platform-browser/animations/src/module.ts @@ -11,7 +11,9 @@ import {BrowserModule} from '@angular/platform-browser'; import {BROWSER_ANIMATIONS_PROVIDERS, BROWSER_NOOP_ANIMATIONS_PROVIDERS} from './providers'; /** - * @experimental Animation support is experimental. + * Exports `BrowserModule` with additional [dependency-injection providers](guide/glossary#provider) + * for use with animations. See [Animations](guide/animations). + * @experimental */ @NgModule({ exports: [BrowserModule], @@ -21,7 +23,8 @@ export class BrowserAnimationsModule { } /** - * @experimental Animation support is experimental. + * A null player that must be imported to allow disabling of animations. + * @experimental */ @NgModule({ exports: [BrowserModule], diff --git a/packages/platform-browser/src/browser.ts b/packages/platform-browser/src/browser.ts index 6da3936936..87a0cdb67d 100644 --- a/packages/platform-browser/src/browser.ts +++ b/packages/platform-browser/src/browser.ts @@ -89,7 +89,11 @@ export const BROWSER_MODULE_PROVIDERS: StaticProvider[] = [ ]; /** - * The ng module for the browser. + * Exports required infrastructure for all Angular apps. + * Included by defaults in all Angular apps created with the CLI + * `new` command. + * Re-exports `CommonModule` and `ApplicationModule`, making their + * exports and providers available to all apps. * * */ @@ -103,9 +107,12 @@ export class BrowserModule { } /** - * Configures a browser-based application to transition from a server-rendered app, if - * one is present on the page. The specified parameters must include an application id, - * which must match between the client and server applications. + * Configures a browser-based app to transition from a server-rendered app, if + * one is present on the page. + * + * @param params An object containing an identifier for the app to transition. + * The ID must match between the client and server versions of the app. + * @returns The reconfigured `BrowserModule` to import into the app's root `AppModule`. * * @experimental */