docs: test doc for decorator templates (#23902) (#23902)

PR Close #23902

PR Close #23902

packages/core/src/metadata/ng_module.ts

@@ -71,7 +71,7 @@ export interface NgModuleDef<T, Declarations, Imports, Exports> {
 }
 
 /**
- * A wrapper around a module that also includes the providers.
+ * A wrapper around an NgModule that associates it with the providers.
  *
  *
  */
@@ -81,17 +81,21 @@ export interface ModuleWithProviders {
 }
 
 /**
- * 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
  */
 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.
  *
  *
  */
@@ -100,7 +104,7 @@ export 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
  */
@@ -116,7 +120,7 @@ export 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;
@@ -129,12 +133,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 {
@@ -160,9 +165,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.
    *
-   * ### Example
+   * @usageNotes
+   *
+   * The following example allows the CommonModule to use the `NgFor`
+   * directive.
    *
    * ```javascript
    * @NgModule({
@@ -175,11 +183,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({
@@ -188,15 +198,18 @@ 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.
    *
-   * ### Example
+   * @usageNotes
+   *
+   * The following example exports the `NgFor` directive from CommonModule.
    *
    * ```javascript
    * @NgModule({
@@ -209,36 +222,34 @@ 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;
@@ -266,11 +277,12 @@ function preR3NgModuleCompile(moduleType: InjectorType<any>, metadata: NgModule)
 }
 
 /**
- * NgModule decorator and metadata.
- *
- *
  * @Annotation
  */
 export const NgModule: NgModuleDecorator = makeDecorator(
     'NgModule', (ngModule: NgModule) => ngModule, undefined, undefined,
+    /**
+     * Decorator that marks the following class as an NgModule, and supplies
+     * configuration metadata for it.
+     */
     (type: Type<any>, meta: NgModule) => (R3_COMPILE_NGMODULE || preR3NgModuleCompile)(type, meta));