docs(core): add docs to Property and Event

vsavkin · vsavkin · commit ce6b364dc5a1 · 2015-09-24T13:46:29.000-07:00
diff --git a/modules/angular2/src/core/metadata.ts b/modules/angular2/src/core/metadata.ts
@@ -454,17 +454,7 @@ export interface PipeFactory {
 /**
  * {@link PropertyMetadata} factory for creating decorators.
  *
- * ## Example as TypeScript Decorator
- *
- * ```
- * @Directive({
- *   selector: 'sample-dir'
- * })
- * class SampleDir {
- *   @Property() property; // Same as @Property('property') property;
- *   @Property("el-property") dirProperty;
- * }
- * ```
+ * See {@link PropertyMetadata}.
  */
 export interface PropertyFactory {
   (bindingPropertyName?: string): any;
@@ -474,17 +464,7 @@ export interface PropertyFactory {
 /**
  * {@link EventMetadata} factory for creating decorators.
  *
- * ## Example as TypeScript Decorator
- *
- * ```
- * @Directive({
- *   selector: 'sample-dir'
- * })
- * class SampleDir {
- *   @Event() event = new EventEmitter(); // Same as @Event('event') event = new EventEmitter();
- *   @Event("el-event") dirEvent = new EventEmitter();
- * }
- * ```
+ * See {@link EventMetadata}.
  */
 export interface EventFactory {
   (bindingPropertyName?: string): any;
@@ -588,11 +568,15 @@ export var Pipe: PipeFactory = <PipeFactory>makeDecorator(PipeMetadata);
 
 /**
  * {@link PropertyMetadata} factory function.
+ *
+ * See {@link PropertyMetadata}.
  */
 export var Property: PropertyFactory = makePropDecorator(PropertyMetadata);
 
 /**
  * {@link EventMetadata} factory function.
+ *
+ * See {@link EventMetadata}.
  */
 export var Event: EventFactory = makePropDecorator(EventMetadata);
 
diff --git a/modules/angular2/src/core/metadata/directives.ts b/modules/angular2/src/core/metadata/directives.ts
@@ -417,116 +417,98 @@ export class DirectiveMetadata extends InjectableMetadata {
   selector: string;
 
   /**
-   * Enumerates the set of properties that accept data binding for a directive.
+   * Enumerates the set of data-bound properties for a directive
+   *
+   * Angular automatically updates data-bound properties during change detection.
    *
    * The `properties` property defines a set of `directiveProperty` to `bindingProperty`
    * configuration:
    *
    * - `directiveProperty` specifies the component property where the value is written.
    * - `bindingProperty` specifies the DOM property where the value is read from.
    *
-   * You can include a {@link PipeMetadata} when specifying a `bindingProperty` to allow for data
-   * transformation and structural change detection of the value. These pipes will be evaluated in
-   * the context of this component.
-   *
-   * ## Syntax
-   *
-   * There is no need to specify both `directiveProperty` and `bindingProperty` when they both have
-   * the same value.
-   *
-   * ```
-   * @Directive({
-   *   properties: [
-   *     'propertyName', // shorthand notation for 'propertyName: propertyName'
-   *     'directiveProperty1: bindingProperty1',
-   *     'directiveProperty2: bindingProperty2 | pipe1 | ...',
-   *     ...
-   *   ]
-   * }
-   * ```
-   *
+   * When `bindingProperty` is not provided, it is assumed to be equal to `directiveProperty`.
    *
-   * ## Basic Property Binding
+   * ### Example ([live demo](http://plnkr.co/edit/ivhfXY?p=preview))
    *
-   * We can easily build a simple `Tooltip` directive that exposes a `tooltip` property, which can
-   * be used in templates with standard Angular syntax. For example:
+   * The following example creates a component with two data-bound properties.
    *
-   * ```
-   * @Directive({
-   *   selector: '[tooltip]',
-   *   properties: [
-   *     'text: tooltip'
-   *   ]
+   * ```typescript
+   * @Component({
+   *   selector: 'bank-account',
+   *   properties: ['bankName', 'id: account-id']
    * })
-   * class Tooltip {
-   *   set text(value: string) {
-   *     // This will get called every time with the new value when the 'tooltip' property changes
-   *   }
-   * }
-   * ```
-   *
-   * We can then bind to the `tooltip' property as either an expression (`someExpression`) or as a
-   * string literal, as shown in the HTML template below:
-   *
-   * ```html
-   * <div [tooltip]="someExpression">...</div>
-   * <div tooltip="Some Text">...</div>
-   * ```
-   *
-   * Whenever the `someExpression` expression changes, the `properties` declaration instructs
-   * Angular to update the `Tooltip`'s `text` property.
+   * @View({
+   *   template: `
+   *     Bank Name: {{bankName}}
+   *     Account Id: {{id}}
+   *   `
+   * })
+   * class BankAccount {
+   *   bankName: string;
+   *   id: string;
    *
-   * ### Bindings With Pipes
+   *   // this property is not bound, and won't be automatically updated by Angular
+   *   normalizedBankName: string;
+   * }
    *
-   * You can use pipes in bindings, as follows:
+   * @Component({selector: 'app'})
+   * @View({
+   *   template: `
+   *     <bank-account bank-name="RBC" account-id="4747"></bank-account>
+   *   `,
+   *   directives: [BankAccount]
+   * })
+   * class App {}
    *
-   * ```html
-   * <div [class-set]="someExpression | somePipe">
+   * bootstrap(App);
    * ```
    *
    */
   properties: string[];
 
   /**
-   * Enumerates the set of emitted events.
+   * Enumerates the set of event-bound properties.
    *
-   * ## Syntax
-   *
-   * ```
-   * @Component({
-   *   events: ['statusChange']
-   * })
-   * class TaskComponent {
-   *   statusChange: EventEmitter;
+   * When an event-bound property emits an event, an event handler attached to that event
+   * the template is invoked.
    *
-   *   constructor() {
-   *     this.statusChange = new EventEmitter();
-   *   }
+   * The `events` property defines a set of `directiveProperty` to `bindingProperty`
+   * configuration:
    *
-   *   onComplete() {
-   *     this.statusChange.next('completed');
-   *   }
-   * }
-   * ```
+   * - `directiveProperty` specifies the component property that emits events.
+   * - `bindingProperty` specifies the DOM property the event handler is attached to.
    *
-   * Use `propertyName: eventName` when the event emitter property name is different from the name
-   * of the emitted event:
+   * ### Example ([live demo](http://plnkr.co/edit/d5CNq7?p=preview))
    *
-   * ```
-   * @Component({
-   *   events: ['status: statusChange']
+   * ```typescript
+   * @Directive({
+   *   selector: 'interval-dir',
+   *   events: ['everySecond', 'five5Secs: everyFiveSeconds']
    * })
-   * class TaskComponent {
-   *   status: EventEmitter;
+   * class IntervalDir {
+   *   everySecond = new EventEmitter();
+   *   five5Secs = new EventEmitter();
    *
    *   constructor() {
-   *     this.status = new EventEmitter();
+   *     setInterval(() => this.everySecond.next("event"), 1000);
+   *     setInterval(() => this.five5Secs.next("event"), 5000);
    *   }
+   * }
    *
-   *   onComplete() {
-   *     this.status.next('completed');
-   *   }
+   * @Component({selector: 'app'})
+   * @View({
+   *   template: `
+   *     <interval-dir (every-second)="everySecond()" (every-five-seconds)="everyFiveSeconds()">
+   *     </interval-dir>
+   *   `,
+   *   directives: [IntervalDir]
+   * })
+   * class App {
+   *   everySecond() { console.log('second'); }
+   *   everyFiveSeconds() { console.log('five seconds'); }
    * }
+   * bootstrap(App);
    * ```
    *
    */
@@ -940,38 +922,94 @@ export class PipeMetadata extends InjectableMetadata {
 }
 
 /**
- * Declare a bound field.
+ * Declares a data-bound property.
  *
- * ## Example
+ * Angular automatically updates data-bound properties during change detection.
  *
- * ```
- * @Directive({
- *   selector: 'sample-dir'
+ * `PropertyMetadata` takes an optional parameters that specifies that name
+ * used when instantiating a component in the template. When not provided,
+ * the class property name is used.
+ *
+ * ### Example
+ *
+ * The following example creates a component with two data-bound properties.
+ *
+ * ```typescript
+ * @Component({selector: 'bank-account'})
+ * @View({
+ *   template: `
+ *     Bank Name: {{bankName}}
+ *     Account Id: {{id}}
+ *   `
  * })
- * class SampleDir {
- *   @Property() property; // Same as @Property('property') property;
- *   @Property("el-property") dirProperty;
+ * class BankAccount {
+ *   @Property() bankName: string;
+ *   @Property('account-id') id: string;
+ *
+ *   // this property is not bound, and won't be automatically updated by Angular
+ *   normalizedBankName: string;
  * }
+ *
+ * @Component({selector: 'app'})
+ * @View({
+ *   template: `
+ *     <bank-account bank-name="RBC" account-id="4747"></bank-account>
+ *   `,
+ *   directives: [BankAccount]
+ * })
+ * class App {}
+ *
+ * bootstrap(App);
  * ```
  */
 @CONST()
 export class PropertyMetadata {
-  constructor(public bindingPropertyName?: string) {}
+  constructor(
+      /**
+       * Name used when instantiating a component in the temlate.
+       */
+      public bindingPropertyName?: string) {}
 }
 
 /**
- * Declare a bound event.
+ * Declares an event-bound property.
  *
- * ## Example
+ * When an event-bound property emits an event, an event handler attached to that event
+ * the template is invoked.
  *
- * ```
+ * `EventMetadata` takes an optional parameters that specifies that name
+ * used when instantiating a component in the template. When not provided,
+ * the class property name is used.
+ *
+ * ### Example
+ *
+ * ```typescript
  * @Directive({
- *   selector: 'sample-dir'
+ *   selector: 'interval-dir',
  * })
- * class SampleDir {
- *   @Event() event = new EventEmitter(); // Same as @Event('event') event = new EventEmitter();
- *   @Event("el-event") dirEvent = new EventEmitter();
+ * class IntervalDir {
+ *   @Event() everySecond = new EventEmitter();
+ *   @Event('everyFiveSeconds') five5Secs = new EventEmitter();
+ *
+ *   constructor() {
+ *     setInterval(() => this.everySecond.next("event"), 1000);
+ *     setInterval(() => this.five5Secs.next("event"), 5000);
+ *   }
  * }
+ *
+ * @Component({selector: 'app'})
+ * @View({
+ *   template: `
+ *     <interval-dir (every-second)="everySecond()" (every-five-seconds)="everyFiveSeconds()">
+ *     </interval-dir>
+ *   `,
+ *   directives: [IntervalDir]
+ * })
+ * class App {
+ *   everySecond() { console.log('second'); }
+ *   everyFiveSeconds() { console.log('five seconds'); }
+ * }
+ * bootstrap(App);
  * ```
  */
 @CONST()
@@ -980,9 +1018,11 @@ export class EventMetadata {
 }
 
 /**
- * Declare a host property binding.
+ * Declares a host binding property.
  *
- * ## Example
+ * Angular automatically updates data-bound properties during change detection.
+ *
+ * ### Example
  *
  * ```
  * @Directive({
