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

PR Close #23902

PR Close #23902

packages/common/http/src/module.ts

@@ -19,12 +19,13 @@ import {BrowserXhr, HttpXhrBackend, XhrFactory} from './xhr';
 import {HttpXsrfCookieExtractor, HttpXsrfInterceptor, HttpXsrfTokenExtractor, XSRF_COOKIE_NAME, XSRF_HEADER_NAME} from './xsrf';
 
 /**
- * An `HttpHandler` that applies a bunch of `HttpInterceptor`s
+ * An injectable `HttpHandler` that applies multiple interceptors
  * to a request before passing it to the given `HttpBackend`.
  *
  * The interceptors are loaded lazily from the injector, to allow
  * interceptors to themselves inject classes depending indirectly
  * on `HttpInterceptingHandler` itself.
+ * @see `HttpInterceptor`
  */
 @Injectable()
 export class HttpInterceptingHandler implements HttpHandler {
@@ -42,6 +43,23 @@ export class HttpInterceptingHandler implements HttpHandler {
   }
 }
 
+/**
+ * Constructs an `HttpHandler` that applies interceptors
+ * to a request before passing it to the given `HttpBackend`.
+ *
+ * Use as a factory function within `HttpClientModule`.
+ *
+ *
+ */
+export function interceptingHandler(
+    backend: HttpBackend, interceptors: HttpInterceptor[] | null = []): HttpHandler {
+  if (!interceptors) {
+    return backend;
+  }
+  return interceptors.reduceRight(
+      (next, interceptor) => new HttpInterceptorHandler(next, interceptor), backend);
+}
+
 /**
  * Factory function that determines where to store JSONP callbacks.
  *
@@ -58,14 +76,14 @@ export function jsonpCallbackContext(): Object {
 }
 
 /**
- * `NgModule` which adds XSRF protection support to outgoing requests.
+ * An NgModule that adds XSRF protection support to outgoing requests.
  *
- * Provided the server supports a cookie-based XSRF protection system, this
- * module can be used directly to configure XSRF protection with the correct
+ * For a server that supports a cookie-based XSRF protection system,
+ * use directly to configure XSRF protection with the correct
  * cookie and header names.
  *
- * If no such names are provided, the default is to use `X-XSRF-TOKEN` for
- * the header name and `XSRF-TOKEN` for the cookie name.
+ * If no names are supplied, the default cookie name is `XSRF-TOKEN`
+ * and the default header name is `X-XSRF-TOKEN`.
  *
  *
  */
@@ -92,8 +110,12 @@ export class HttpClientXsrfModule {
   }
 
   /**
-   * Configure XSRF protection to use the given cookie name or header name,
-   * or the default names (as described above) if not provided.
+   * Configure XSRF protection.
+   * @param options An object that can specify either or both
+   * cookie name or header name.
+   * - Cookie name default is `XSRF-TOKEN`.
+   * - Header name default is `X-XSRF-TOKEN`.
+   *
    */
   static withOptions(options: {
     cookieName?: string,
@@ -110,7 +132,7 @@ export class HttpClientXsrfModule {
 }
 
 /**
- * `NgModule` which provides the `HttpClient` and associated services.
+ * An NgModule that provides the `HttpClient` and associated services.
  *
  * Interceptors can be added to the chain behind `HttpClient` by binding them
  * to the multiprovider for `HTTP_INTERCEPTORS`.
@@ -118,12 +140,18 @@ export class HttpClientXsrfModule {
  *
  */
 @NgModule({
+  /**
+   * Optional configuration for XSRF protection.
+   */
   imports: [
     HttpClientXsrfModule.withOptions({
       cookieName: 'XSRF-TOKEN',
       headerName: 'X-XSRF-TOKEN',
     }),
   ],
+  /**
+   * The module provides `HttpClient` itself, and supporting services.
+   */
   providers: [
     HttpClient,
     {provide: HttpHandler, useClass: HttpInterceptingHandler},
@@ -137,7 +165,7 @@ export class HttpClientModule {
 }
 
 /**
- * `NgModule` which enables JSONP support in `HttpClient`.
+ * An NgModule that enables JSONP support in `HttpClient`.
  *
  * Without this module, Jsonp requests will reach the backend
  * with method JSONP, where they'll be rejected.

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));

packages/examples/core/ts/metadata/directives.ts

@@ -0,0 +1,66 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+/* tslint:disable:no-console  */
+import {Component, Directive, EventEmitter} from '@angular/core';
+
+// #docregion component-input
+@Component({
+  selector: 'app-bank-account',
+  inputs: ['bankName', 'id: account-id'],
+  template: `
+    Bank Name: {{ bankName }}
+    Account Id: {{ id }}
+  `
+})
+export class BankAccountComponent {
+  bankName: string;
+  id: string;
+
+  // this property is not bound, and won't be automatically updated by Angular
+  normalizedBankName: string;
+}
+
+@Component({
+  selector: 'app-my-input',
+  template: `
+    <app-bank-account
+      bankName="RBC"
+      account-id="4747">
+    </app-bank-account>
+  `
+})
+export class MyInputComponent {
+}
+// #enddocregion component-input
+
+// #docregion component-output-interval
+@Directive({selector: 'app-interval-dir', outputs: ['everySecond', 'fiveSecs: everyFiveSeconds']})
+export class IntervalDirComponent {
+  everySecond = new EventEmitter<string>();
+  fiveSecs = new EventEmitter<string>();
+
+  constructor() {
+    setInterval(() => this.everySecond.emit('event'), 1000);
+    setInterval(() => this.fiveSecs.emit('event'), 5000);
+  }
+}
+
+@Component({
+  selector: 'app-my-output',
+  template: `
+    <app-interval-dir
+      (everySecond)="onEverySecond()"
+      (everyFiveSeconds)="onEveryFiveSeconds()">
+    </app-interval-dir>
+  `
+})
+export class MyOutputComponent {
+  onEverySecond() { console.log('second'); }
+  onEveryFiveSeconds() { console.log('five seconds'); }
+}
+// #enddocregion component-output-interval