Fix and complete decorator API doc

packages/core/src/di/metadata.ts

@@ -237,41 +237,25 @@ export const Host: HostDecorator = makeParamDecorator('Host');
  */
 export interface AttributeDecorator {
   /**
-   * Specifies that a constant attribute value should be injected.
-   *
-   * The directive can inject constant string literals of host element attributes.
+   * A parameter decorator for a directive constructor that designates
+   * a host-element attribute whose value is injected as a constant string literal.
    *
    * @usageNotes
-   * ### Example
    *
    * Suppose we have an `<input>` element and want to know its `type`.
    *
    * ```html
    * <input type="text">
    * ```
    *
-   * A decorator can inject string literal `text` like so:
+   * The following example uses the decorator to inject the string literal `text`.
    *
    * {@example core/ts/metadata/metadata.ts region='attributeMetadata'}
    *
    * ### Example as TypeScript Decorator
    *
    * {@example core/ts/metadata/metadata.ts region='attributeFactory'}
    *
-   * ### Example as ES5 annotation
-   *
-   * ```
-   * var MyComponent = function(title) {
-   *   ...
-   * };
-   *
-   * MyComponent.annotations = [
-   *   new ng.Component({...})
-   * ]
-   * MyComponent.parameters = [
-   *   [new ng.Attribute('title')]
-   * ]
-   * ```
    */
   (name: string): any;
   new (name: string): Attribute;
@@ -282,7 +266,12 @@ export interface AttributeDecorator {
  *
  * @publicApi
  */
-export interface Attribute { attributeName?: string; }
+export interface Attribute {
+  /**
+   * The name of the attribute whose value can be injected.
+   */
+  attributeName?: string;
+}
 
 /**
  * Attribute decorator and metadata.

packages/core/src/metadata.ts

@@ -22,6 +22,6 @@ export {Attribute} from './di';
 export {AfterContentChecked, AfterContentInit, AfterViewChecked, AfterViewInit, DoCheck, OnChanges, OnDestroy, OnInit} from './interface/lifecycle_hooks';
 export {ANALYZE_FOR_ENTRY_COMPONENTS, ContentChild, ContentChildDecorator, ContentChildren, ContentChildrenDecorator, Query, ViewChild, ViewChildDecorator, ViewChildren, ViewChildrenDecorator} from './metadata/di';
 export {Component, ComponentDecorator, Directive, DirectiveDecorator, HostBinding, HostBindingDecorator, HostListener, HostListenerDecorator, Input, InputDecorator, Output, OutputDecorator, Pipe, PipeDecorator} from './metadata/directives';
-export {DoBootstrap, ModuleWithProviders, NgModule} from './metadata/ng_module';
+export {DoBootstrap, ModuleWithProviders, NgModule, NgModuleDecorator} from './metadata/ng_module';
 export {CUSTOM_ELEMENTS_SCHEMA, NO_ERRORS_SCHEMA, SchemaMetadata} from './metadata/schema';
 export {ViewEncapsulation} from './metadata/view';

packages/core/src/metadata/directives.ts

@@ -317,7 +317,7 @@ export interface ComponentDecorator {
    *
    * A component must belong to an NgModule in order for it to be available
    * to another component or application. To make it a member of an NgModule,
-   * list it in the `declarations` field of the `@NgModule` metadata.
+   * list it in the `declarations` field of the `NgModule` metadata.
    *
    * Note that, in addition to these options for configuring a directive,
    * you can control a component's runtime behavior by implementing
@@ -443,7 +443,7 @@ export interface ComponentDecorator {
    */
   (obj: Component): TypeDecorator;
   /**
-   * See the `@Component` decorator.
+   * See the `Component` decorator.
    */
   new (obj: Component): Component;
 }
@@ -572,7 +572,22 @@ export const Component: ComponentDecorator = makeDecorator(
  */
 export interface PipeDecorator {
   /**
-   * Declares a reusable pipe function, and supplies configuration metadata.
+   *
+   * Decorator that marks a class as pipe and supplies configuration metadata.
+   *
+   * A pipe class must implement the `PipeTransform` interface.
+   * For example, if the name is "myPipe", use a template binding expression
+   * such as the following:
+   *
+   * ```
+   * {{ exp | myPipe }}
+   * ```
+   *
+   * The result of the expression is passed to the pipe's `transform()` method.
+   *
+   * A pipe must belong to an NgModule in order for it to be available
+   * to a template. To make it a member of an NgModule,
+   * list it in the `declarations` field of the `NgModule` metadata.
    *
    */
   (obj: Pipe): TypeDecorator;
@@ -622,23 +637,48 @@ export const Pipe: PipeDecorator = makeDecorator(
  */
 export interface InputDecorator {
   /**
-   * Decorator that marks a class as pipe and supplies configuration metadata.
-   *
-   * A pipe class must implement the `PipeTransform` interface.
-   * For example, if the name is "myPipe", use a template binding expression
-   * such as the following:
-   *
-   * ```
-   * {{ exp | myPipe }}
-   * ```
-   *
-   * The result of the expression is passed to the pipe's `transform()` method.
-   *
-   * A pipe must belong to an NgModule in order for it to be available
-   * to a template. To make it a member of an NgModule,
-   * list it in the `declarations` field of the `@NgModule` metadata.
-   *
-   */
+  * Decorator that marks a class field as an input property and supplies configuration metadata.
+  * The input property is bound to a DOM property in the template. During change detection,
+  * Angular automatically updates the data property with the DOM property's value.
+  *
+  * @usageNotes
+  *
+  * You can supply an optional name to use in templates when the
+  * component is instantiated, that maps to the
+  * name of the bound property. By default, the original
+  * name of the bound property is used for input binding.
+  *
+  * The following example creates a component with two input properties,
+  * one of which is given a special binding name.
+  *
+  * ```typescript
+  * @Component({
+  *   selector: 'bank-account',
+  *   template: `
+  *     Bank Name: {{bankName}}
+  *     Account Id: {{id}}
+  *   `
+  * })
+  * class BankAccount {
+  *   // This property is bound using its original name.
+  *   @Input() bankName: string;
+  *   // this property value is bound to a different property name
+  *   // when this component is instantiated in a template.
+  *   @Input('account-id') id: string;
+  *
+  *   // this property is not bound, and is not automatically updated by Angular
+  *   normalizedBankName: string;
+  * }
+  *
+  * @Component({
+  *   selector: 'app',
+  *   template: `
+  *     <bank-account bankName="RBC" account-id="4747"></bank-account>
+  *   `
+  * })
+  * class App {}
+  * ```
+  */
   (bindingPropertyName?: string): any;
   new (bindingPropertyName?: string): any;
 }
@@ -650,49 +690,7 @@ export interface InputDecorator {
  */
 export interface Input {
   /**
-   * Decorator that marks a class field as an input property and supplies configuration metadata.
-   * Declares a data-bound input property, which Angular automatically updates
-   * during change detection.
-   *
-   * @usageNotes
-   *
-   * You can supply an optional name to use in templates when the
-   * component is instantiated, that maps to the
-   * name of the bound property. By default, the original
-   * name of the bound property is used for input binding.
-   *
-   * The following example creates a component with two input properties,
-   * one of which is given a special binding name.
-   *
-   * ```typescript
-   * @Component({
-   *   selector: 'bank-account',
-   *   template: `
-   *     Bank Name: {{bankName}}
-   *     Account Id: {{id}}
-   *   `
-   * })
-   * class BankAccount {
-   *   // This property is bound using its original name.
-   *   @Input() bankName: string;
-   *   // this property value is bound to a different property name
-   *   // when this component is instantiated in a template.
-   *   @Input('account-id') id: string;
-   *
-   *   // this property is not bound, and is not automatically updated by Angular
-   *   normalizedBankName: string;
-   * }
-   *
-   * @Component({
-   *   selector: 'app',
-   *   template: `
-   *     <bank-account bankName="RBC" account-id="4747"></bank-account>
-   *   `
-   * })
-   *
-   * class App {}
-   * ```
-   *
+   * The name of the DOM property to which the input property is bound.
    */
   bindingPropertyName?: string;
 }
@@ -715,7 +713,7 @@ const initializeBaseDef = (target: any): void => {
 };
 
 /**
- * Does the work of creating the `ngBaseDef` property for the @Input and @Output decorators.
+ * Does the work of creating the `ngBaseDef` property for the `Input` and `Output` decorators.
  * @param key "inputs" or "outputs"
  */
 const updateBaseDefFromIOProp = (getProp: (baseDef: {inputs?: any, outputs?: any}) => any) =>
@@ -747,8 +745,7 @@ export const Input: InputDecorator = makePropDecorator(
 export interface OutputDecorator {
   /**
   * Decorator that marks a class field as an output property and supplies configuration metadata.
-  * Declares a data-bound output property, which Angular automatically updates
-  * during change detection.
+  * The DOM property bound to the output property is automatically updated during change detection.
   *
   * @usageNotes
   *
@@ -757,7 +754,7 @@ export interface OutputDecorator {
   * name of the bound property. By default, the original
   * name of the bound property is used for output binding.
   *
-  * See `@Input` decorator for an example of providing a binding name.
+  * See `Input` decorator for an example of providing a binding name.
   *
   */
   (bindingPropertyName?: string): any;
@@ -769,7 +766,12 @@ export interface OutputDecorator {
  *
  * @publicApi
  */
-export interface Output { bindingPropertyName?: string; }
+export interface Output {
+  /**
+  * The name of the DOM property to which the output property is bound.
+  */
+  bindingPropertyName?: string;
+}
 
 /**
  * @Annotation
@@ -825,7 +827,12 @@ export interface HostBindingDecorator {
  *
  * @publicApi
  */
-export interface HostBinding { hostPropertyName?: string; }
+export interface HostBinding {
+  /**
+   * The DOM property that is bound to a data property.
+   */
+  hostPropertyName?: string;
+}
 
 /**
  * @Annotation
@@ -841,6 +848,10 @@ export const HostBinding: HostBindingDecorator =
  * @publicApi
  */
 export interface HostListenerDecorator {
+  /**
+   * Decorator that declares a DOM event to listen for,
+   * and provides a handler method to run when that event occurs.
+   */
   (eventName: string, args?: string[]): any;
   new (eventName: string, args?: string[]): any;
 }

packages/core/src/metadata/ng_module.ts

@@ -91,10 +91,12 @@ export interface ModuleWithProviders<
 
 /**
  * Type of the NgModule decorator / constructor function.
+ *
+ * @publicApi
  */
 export interface NgModuleDecorator {
   /**
-   * Marks a class as an NgModule and supplies configuration metadata.
+   * Decorator that marks a class as an NgModule and supplies configuration metadata.
    */
   (obj?: NgModule): TypeDecorator;
   new (obj?: NgModule): NgModule;

tools/public_api_guard/core/core.d.ts

@@ -574,6 +574,11 @@ export interface NgModule {
 
 export declare const NgModule: NgModuleDecorator;
 
+export interface NgModuleDecorator {
+    (obj?: NgModule): TypeDecorator;
+    new (obj?: NgModule): NgModule;
+}
+
 export declare abstract class NgModuleFactory<T> {
     abstract readonly moduleType: Type<T>;
     abstract create(parentInjector: Injector | null): NgModuleRef<T>;