docs(core): add docs to HostBinding and HostListener

modules/angular2/src/core/metadata.ts

@@ -472,19 +472,7 @@ export interface OutputFactory {
 }
 
 /**
- * {@link HostBindingMetadata} factory for creating decorators.
+ * {@link HostBindingMetadata} factory function.
- *
- * ## Example as TypeScript Decorator
- *
- * ```
- * @Directive({
- *   selector: 'sample-dir'
- * })
- * class SampleDir {
- *   @HostBinding() prop1; // Same as @HostBinding('prop1') prop1;
- *   @HostBinding("el-prop") prop1;
- * }
- * ```
  */
 export interface HostBindingFactory {
   (hostPropertyName?: string): any;
@@ -492,18 +480,7 @@ export interface HostBindingFactory {
 }
 
 /**
- * {@link HostListenerMetadata} factory for creating decorators.
+ * {@link HostListenerMetadata} factory function.
- *
- * ## Example as TypeScript Decorator
- *
- * ```
- * @Directive({
- *   selector: 'sample-dir'
- * })
- * class SampleDir {
- *   @HostListener("change", ['$event.target.value']) onChange(value){}
- * }
- * ```
  */
 export interface HostListenerFactory {
   (eventName: string, args?: string[]): any;

modules/angular2/src/core/metadata/directives.ts

@@ -517,9 +517,9 @@ export class DirectiveMetadata extends InjectableMetadata {
   /**
    * Specify the events, actions, properties and attributes related to the host element.
    *
-   * ## Events
+   * ## Host Listeners
    *
-   * Specifies which DOM hostListeners a directive listens to via a set of `(event)` to `method`
+   * Specifies which DOM events a directive listens to via a set of `(event)` to `method`
    * key-value pairs:
    *
    * - `event1`: the DOM event that the directive listens to.
@@ -530,76 +530,86 @@ export class DirectiveMetadata extends InjectableMetadata {
    * To listen to global events, a target must be added to the event name.
    * The target can be `window`, `document` or `body`.
    *
-   * When writing a directive event binding, you can also refer to the following local variables:
+   * When writing a directive event binding, you can also refer to the $event local variable.
-   * - `$event`: Current event object which triggered the event.
-   * - `$target`: The source of the event. This will be either a DOM element or an Angular
-   * directive. (will be implemented in later release)
    *
-   * ## Syntax
+   * ### Example ([live demo](http://plnkr.co/edit/DlA5KU?p=preview))
    *
-   * ```
+   * The following example declares a directive that attaches a click listener to the button and
+   * counts clicks.
+   *
+   * ```typescript
    * @Directive({
+   *   selector: 'button[counting]',
    *   host: {
-   *     '(event1)': 'onMethod1(arguments)',
+   *     '(click)': 'onClick($event.target)'
-   *     '(target:event2)': 'onMethod2(arguments)',
-   *     ...
-   *   }
-   * }
-   * ```
-   *
-   * ## Basic Event Binding:
-   *
-   * Suppose you want to write a directive that reacts to `change` events in the DOM and on
-   * `resize` events in window.
-   * You would define the event binding as follows:
-   *
-   * ```
-   * @Directive({
-   *   selector: 'input',
-   *   host: {
-   *     '(change)': 'onChange($event)',
-   *     '(window:resize)': 'onResize($event)'
    *   }
    * })
-   * class InputDirective {
+   * class CountClicks {
-   *   onChange(event:Event) {
+   *   numberOfClicks = 0;
-   *     // invoked when the input element fires the 'change' event
+   *
-   *   }
+   *   onClick(btn) {
-   *   onResize(event:Event) {
+   *     console.log("button", btn, "number of clicks:", this.numberOfClicks++);
-   *     // invoked when the window fires the 'resize' event
    *   }
    * }
+   *
+   * @Component({selector: 'app'})
+   * @View({
+   *   template: `<button counting>Increment</button>`,
+   *   directives: [CountClicks]
+   * })
+   * class App {}
+   *
+   * bootstrap(App);
    * ```
    *
-   * ## Properties
+   * ## Host Property Bindings
    *
-   * Specifies which DOM properties a directives updates.
+   * Specifies which DOM properties a directive updates.
    *
-   * ## Syntax
+   * Angular automatically checks host property bindings during change detection.
+   * If a binding changes, it will update the host element of the directive.
    *
-   * ```
+   * ### Example ([live demo](http://plnkr.co/edit/gNg0ED?p=preview))
+   *
+   * The following example creates a directive that sets the `valid` and `invalid` classes
+   * on the DOM element that has ng-model directive on it.
+   *
+   * ```typescript
    * @Directive({
-   *   selector: 'input',
+   *   selector: '[ng-model]',
    *   host: {
-   *     '[prop]': 'expression'
+   *     '[class.valid]': 'valid',
+   *     '[class.invalid]': 'invalid'
    *   }
    * })
-   * class InputDirective {
+   * class NgModelStatus {
-   *   value:string;
+   *   constructor(public control:NgModel) {}
+   *   get valid { return this.control.valid; }
+   *   get invalid { return this.control.invalid; }
    * }
-   * ```
    *
-   * In this example the `prop` property of the host element is updated with the expression value
+   * @Component({selector: 'app'})
-   * every time it changes.
+   * @View({
+   *   template: `<input [(ng-model)]="prop">`,
+   *   directives: [FORM_DIRECTIVES, NgModelStatus]
+   * })
+   * class App {
+   *   prop;
+   * }
+   *
+   * bootstrap(App);
+   * ```
    *
    * ## Attributes
    *
-   * Specifies static attributes that should be propagated to a host element. Attributes specified
+   * Specifies static attributes that should be propagated to a host element.
-   * in `hostAttributes` are propagated only if a given attribute is not present on a host element.
    *
-   * ## Syntax
+   * ### Example
    *
-   * ```
+   * In this example using `my-button` directive (ex.: `<div my-button></div>`) on a host element
+   * (here: `<div>` ) will ensure that this element will get the "button" role.
+   *
+   * ```typescript
    * @Directive({
    *   selector: '[my-button]',
    *   host: {
@@ -609,10 +619,6 @@ export class DirectiveMetadata extends InjectableMetadata {
    * class MyButton {
    * }
    * ```
-   *
-   * In this example using `my-button` directive (ex.: `<div my-button></div>`) on a host element
-   * (here: `<div>` ) will ensure that this element will get the "button" role.
-   *
    */
   host: StringMap<string, string>;
 
@@ -926,9 +932,9 @@ export class PipeMetadata extends InjectableMetadata {
  *
  * Angular automatically updates data-bound properties during change detection.
  *
- * `InputMetadata` takes an optional parameters that specifies that name
+ * `InputMetadata` takes an optional parameter that specifies the name
  * used when instantiating a component in the template. When not provided,
- * the class property name is used.
+ * the name of the decorated property is used.
  *
  * ### Example
  *
@@ -977,9 +983,9 @@ export class InputMetadata {
  * When an output property emits an event, an event handler attached to that event
  * the template is invoked.
  *
- * `OutputMetadata` takes an optional parameters that specifies that name
+ * `OutputMetadata` takes an optional parameter that specifies the name
  * used when instantiating a component in the template. When not provided,
- * the class property name is used.
+ * the name of the decorated property is used.
  *
  * ### Example
  *
@@ -1018,33 +1024,38 @@ export class OutputMetadata {
 }
 
 /**
- * Declares a host binding property.
+ * Declares a host property binding.
  *
- * Angular automatically updates data-bound properties during change detection.
+ * Angular automatically checks host property bindings during change detection.
+ * If a binding changes, it will update the host element of the directive.
+ *
+ * `HostBindingMetadata` takes an optional parameter that specifies the property
+ * name of the host element that will be updated. When not provided,
+ * the class property name is used.
  *
  * ### Example
  *
- * ```
+ * The following example creates a directive that sets the `valid` and `invalid` classes
- * @Directive({
+ * on the DOM element that has ng-model directive on it.
- *   selector: 'sample-dir'
- * })
- * class SampleDir {
- *   @HostBinding() prop1; // Same as @HostBinding('prop1') prop1;
- *   @HostBinding("el-prop") prop2;
- * }
- * ```
  *
- * This is equivalent to
+ * ```typescript
- *
+ * @Directive({selector: '[ng-model]'})
- * ```
+ * class NgModelStatus {
- * @Directive({
+ *   constructor(public control:NgModel) {}
- *   selector: 'sample-dir',
+ *   @HostBinding('[class.valid]') get valid { return this.control.valid; }
- *   host: {'[prop1]': 'prop1', '[el-prop]': 'prop2'}
+ *   @HostBinding('[class.invalid]') get invalid { return this.control.invalid; }
- * })
- * class SampleDir {
- *   prop1;
- *   prop2;
  * }
+ *
+ * @Component({selector: 'app'})
+ * @View({
+ *   template: `<input [(ng-model)]="prop">`,
+ *   directives: [FORM_DIRECTIVES, NgModelStatus]
+ * })
+ * class App {
+ *   prop;
+ * }
+ *
+ * bootstrap(App);
  * ```
  */
 @CONST()
@@ -1053,29 +1064,37 @@ export class HostBindingMetadata {
 }
 
 /**
- * Declare a host listener.
+ * Declares a host listener.
  *
- * ## Example
+ * Angular will invoke the decorated method when the host element emits the specified event.
  *
- * ```
+ * If the decorated method returns `false`, then `preventDefault` is applied on the DOM
- * @Directive({
+ * event.
- *   selector: 'sample-dir'
+ *
- * })
+ * ### Example
- * class SampleDir {
+ *
- *   @HostListener("change", ['$event.target.value']) onChange(value){}
+ * The following example declares a directive that attaches a click listener to the button and
+ * counts clicks.
+ *
+ * ```typescript
+ * @Directive({selector: 'button[counting]'})
+ * class CountClicks {
+ *   numberOfClicks = 0;
+ *
+ *   @HostListener('click', ['$event.target'])
+ *   onClick(btn) {
+ *     console.log("button", btn, "number of clicks:", this.numberOfClicks++);
  *   }
- * ```
- *
- * This is equivalent to
- *
- * ```
- * @Directive({
- *   selector: 'sample-dir',
- *   host: {'(change)': 'onChange($event.target.value)'}
- * })
- * class SampleDir {
- *   onChange(value){}
  * }
+ *
+ * @Component({selector: 'app'})
+ * @View({
+ *   template: `<button counting>Increment</button>`,
+ *   directives: [CountClicks]
+ * })
+ * class App {}
+ *
+ * bootstrap(App);
  * ```
  */
 @CONST()