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

This reverts commit 3938a8be75.

packages/core/src/metadata/ng_module.ts

@@ -14,7 +14,7 @@ import {TypeDecorator, makeDecorator} from '../util/decorators';
 
 
 /**
- * A wrapper around an NgModule that associates it with the providers.
+ * A wrapper around a module that also includes the providers.
  *
  *
  */
@@ -24,21 +24,17 @@ export interface ModuleWithProviders {
 }
 
 /**
- * A schema definition associated with an NgModule.
- * 
- * @see `@NgModule`, `CUSTOM_ELEMENTS_SCHEMA`, `NO_ERRORS_SCHEMA`
- * 
- * @param name The name of a defined schema.
+ * Interface for schema definitions in @NgModules.
  *
  * @experimental
  */
 export interface SchemaMetadata { name: string; }
 
 /**
- * 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.
+ * 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.
  *
  *
  */
@@ -47,7 +43,7 @@ export const CUSTOM_ELEMENTS_SCHEMA: SchemaMetadata = {
 };
 
 /**
- * Defines a schema that allows any property on any element.
+ * Defines a schema that will allow any property on any element.
  *
  * @experimental
  */
@@ -63,7 +59,7 @@ export const NO_ERRORS_SCHEMA: SchemaMetadata = {
  */
 export interface NgModuleDecorator {
   /**
-   * Marks a class as an NgModule and supplies configuration metadata.
+   * Defines an NgModule.
    */
   (obj?: NgModule): TypeDecorator;
   new (obj?: NgModule): NgModule;
@@ -76,13 +72,12 @@ export interface NgModuleDecorator {
  */
 export interface NgModule {
   /**
-   * The set of injectable objects that are available in the injector
+   * Defines the set of injectable objects that are available in the injector
    * of this module.
    *
-   * @usageNotes
+   * ## Simple Example
    *
-   * The following example defines a class that is injected in
-   * the HelloWorld NgModule:
+   * Here is an example of a class that can be injected:
    *
    * ```
    * class Greeter {
@@ -108,12 +103,9 @@ export interface NgModule {
   providers?: Provider[];
 
   /**
-   * The set of directives and pipes that belong to this module.
+   * Specifies a list of directives/pipes that belong to this module.
    *
-   * @usageNotes
-   *
-   * The following example allows the CommonModule to use the `NgFor`
-   * directive.
+   * ### Example
    *
    * ```javascript
    * @NgModule({
@@ -126,13 +118,11 @@ export interface NgModule {
   declarations?: Array<Type<any>|any[]>;
 
   /**
-   * The set of NgModules, with or without providers,
-   * whose exported directives/pipes
-   * are available to templates in this module.
+   * Specifies a list of modules whose exported directives/pipes
+   * should be available to templates in this module.
+   * This can also contain {@link ModuleWithProviders}.
    *
-   * @usageNotes
-   *
-   * The following example allows MainModule to use CommonModule:
+   * ### Example
    *
    * ```javascript
    * @NgModule({
@@ -141,18 +131,15 @@ export interface NgModule {
    * class MainModule {
    * }
    * ```
-   *  @see {@link ModuleWithProviders}
    */
   imports?: Array<Type<any>|ModuleWithProviders|any[]>;
 
   /**
-   * 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.
+   * 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.
    *
-   * @usageNotes
-   *
-   * The following example exports the `NgFor` directive from CommonModule.
+   * ### Example
    *
    * ```javascript
    * @NgModule({
@@ -165,40 +152,45 @@ export interface NgModule {
   exports?: Array<Type<any>|any[]>;
 
   /**
-   * 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`.
+   * 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}.
    */
   entryComponents?: Array<Type<any>|any[]>;
 
   /**
-   * The set of components that are bootstrapped when
+   * Defines the components that should be bootstrapped when
    * this module is bootstrapped. The components listed here
-   * are automatically added to `entryComponents`.
+   * will automatically be added to `entryComponents`.
    */
   bootstrap?: Array<Type<any>|any[]>;
 
   /**
-   * 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.
+   * Elements and properties that are not Angular components nor directives have to be declared in
+   * the schema.
    *
-   * Allowed value are `NO_ERRORS_SCHEMA` and `CUSTOM_ELEMENTS_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.
    *
-   * @security When using one of `NO_ERRORS_SCHEMA` or `CUSTOM_ELEMENTS_SCHEMA`
-   * you must ensure that allowed elements and properties securely escape inputs.
+   * @security When using one of `NO_ERRORS_SCHEMA` or `CUSTOM_ELEMENTS_SCHEMA` we're trusting that
+   * allowed elements (and its properties) securely escape inputs.
    */
   schemas?: Array<SchemaMetadata|any[]>;
 
   /**
-   * A name or path that uniquely identifies this NgModule in `getModuleFactory`.
-   * If left `undefined`, the NgModule is not registered with
+   * 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
    * `getModuleFactory`.
    */
   id?: string;
 }
 
 /**
+ * NgModule decorator and metadata.
+ *
+ *
  * @Annotation
  */
 export const NgModule: NgModuleDecorator = makeDecorator(
@@ -215,8 +207,3 @@ export const NgModule: NgModuleDecorator = makeDecorator(
         imports: imports,
       });
     });
-    /**
-     * 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));