@angular/core 6.0.6 → 6.0.7

package/src/metadata/ng_module.d.ts

@@ -2,7 +2,7 @@ import { Provider } from '../di/provider';
 import { Type } from '../type';
 import { TypeDecorator } from '../util/decorators';
 /**
- * A wrapper around a module that also includes the providers.
+ * A wrapper around an NgModule that associates it with the providers.
  *
  *
  */
@@ -11,7 +11,11 @@ export interface ModuleWithProviders {
     providers?: Provider[];
 }
 /**
- * Interface for schema definitions in @NgModules.
+ * A schema definition associated with an NgModule.
+ *
+ * @see `@NgModule`, `CUSTOM_ELEMENTS_SCHEMA`, `NO_ERRORS_SCHEMA`
+ *
+ * @param name The name of a defined schema.
  *
  * @experimental
  */
@@ -19,16 +23,16 @@ export interface SchemaMetadata {
     name: string;
 }
 /**
- * Defines a schema that will allow:
- * - any non-Angular elements with a `-` in their name,
- * - any properties on elements with a `-` in their name which is the common rule for custom
- * elements.
+ * Defines a schema that allows an NgModule to contain the following:
+ * - Non-Angular elements named with dash case (`-`).
+ * - Element properties named with dash case (`-`).
+ * Dash case is the naming convention for custom elements.
  *
  *
  */
 export declare const CUSTOM_ELEMENTS_SCHEMA: SchemaMetadata;
 /**
- * Defines a schema that will allow any property on any element.
+ * Defines a schema that allows any property on any element.
  *
  * @experimental
  */
@@ -40,7 +44,7 @@ export declare const NO_ERRORS_SCHEMA: SchemaMetadata;
  */
 export interface NgModuleDecorator {
     /**
-     * Defines an NgModule.
+     * Marks a class as an NgModule and supplies configuration metadata.
      */
     (obj?: NgModule): TypeDecorator;
     new (obj?: NgModule): NgModule;
@@ -52,12 +56,13 @@ export interface NgModuleDecorator {
  */
 export interface NgModule {
     /**
-     * Defines the set of injectable objects that are available in the injector
+     * The set of injectable objects that are available in the injector
      * of this module.
      *
-     * ## Simple Example
+     * @usageNotes
      *
-     * Here is an example of a class that can be injected:
+     * The following example defines a class that is injected in
+     * the HelloWorld NgModule:
      *
      * ```
      * class Greeter {
@@ -82,9 +87,12 @@ export interface NgModule {
      */
     providers?: Provider[];
     /**
-     * Specifies a list of directives/pipes that belong to this module.
+     * The set of directives and pipes that belong to this module.
+     *
+     * @usageNotes
      *
-     * ### Example
+     * The following example allows the CommonModule to use the `NgFor`
+     * directive.
      *
      * ```javascript
      * @NgModule({
@@ -96,11 +104,13 @@ export interface NgModule {
      */
     declarations?: Array<Type<any> | any[]>;
     /**
-     * Specifies a list of modules whose exported directives/pipes
-     * should be available to templates in this module.
-     * This can also contain {@link ModuleWithProviders}.
+     * The set of NgModules, with or without providers,
+     * whose exported directives/pipes
+     * are available to templates in this module.
      *
-     * ### Example
+     * @usageNotes
+     *
+     * The following example allows MainModule to use CommonModule:
      *
      * ```javascript
      * @NgModule({
@@ -109,14 +119,17 @@ export interface NgModule {
      * class MainModule {
      * }
      * ```
+     *  @see {@link ModuleWithProviders}
      */
     imports?: Array<Type<any> | ModuleWithProviders | any[]>;
     /**
-     * Specifies a list of directives/pipes/modules that can be used within the template
-     * of any component that is part of an Angular module
-     * that imports this Angular module.
+     * The set of directives, pipe, and NgModules that can be used
+     * within the template of any component that is part of an
+     * NgModule that imports this NgModule.
+     *
+     * @usageNotes
      *
-     * ### Example
+     * The following example exports the `NgFor` directive from CommonModule.
      *
      * ```javascript
      * @NgModule({
@@ -128,40 +141,38 @@ export interface NgModule {
      */
     exports?: Array<Type<any> | any[]>;
     /**
-     * Specifies a list of components that should be compiled when this module is defined.
-     * For each component listed here, Angular will create a {@link ComponentFactory}
-     * and store it in the {@link ComponentFactoryResolver}.
+     * The set of components to compile when this NgModule is defined.
+     * For each component listed here, Angular creates a `ComponentFactory`
+     * and stores it in the `ComponentFactoryResolver`.
      */
     entryComponents?: Array<Type<any> | any[]>;
     /**
-     * Defines the components that should be bootstrapped when
+     * The set of components that are bootstrapped when
      * this module is bootstrapped. The components listed here
-     * will automatically be added to `entryComponents`.
+     * are automatically added to `entryComponents`.
      */
     bootstrap?: Array<Type<any> | any[]>;
     /**
-     * Elements and properties that are not Angular components nor directives have to be declared in
-     * the schema.
+     * The set of schemas that declare elements to be allowed in the NgModule.
+     * Elements and properties that are neither Angular components nor directives
+     * must be declared in a schema.
      *
-     * Available schemas:
-     * - `NO_ERRORS_SCHEMA`: any elements and properties are allowed,
-     * - `CUSTOM_ELEMENTS_SCHEMA`: any custom elements (tag name has "-") with any properties are
-     *   allowed.
+     * Allowed value are `NO_ERRORS_SCHEMA` and `CUSTOM_ELEMENTS_SCHEMA`.
      *
-     * @security When using one of `NO_ERRORS_SCHEMA` or `CUSTOM_ELEMENTS_SCHEMA` we're trusting that
-     * allowed elements (and its properties) securely escape inputs.
+     * @security When using one of `NO_ERRORS_SCHEMA` or `CUSTOM_ELEMENTS_SCHEMA`
+     * you must ensure that allowed elements and properties securely escape inputs.
      */
     schemas?: Array<SchemaMetadata | any[]>;
     /**
-     * An opaque ID for this module, e.g. a name or a path. Used to identify modules in
-     * `getModuleFactory`. If left `undefined`, the `NgModule` will not be registered with
+     * A name or path that uniquely identifies this NgModule in `getModuleFactory`.
+     * If left `undefined`, the NgModule is not registered with
      * `getModuleFactory`.
      */
     id?: string;
 }
 /**
- * NgModule decorator and metadata.
- *
+ * Decorator that marks the following class as an NgModule, and supplies
+ * configuration metadata for it.
  *
  * @Annotation
  */