docs(NgStyle): update docs, add examples

Closes angular#4519

Author: pkozlowski-opensource

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

@@ -9,25 +9,56 @@ import {Renderer} from 'angular2/src/core/render';
 import {isPresent, isBlank, print} from 'angular2/src/core/facade/lang';
 
 /**
- * Adds or removes styles based on an {expression}.
+ * The `NgStyle` directive changes styles based on a result of expression evaluation.
  *
- * When the expression assigned to `ng-style` evaluates to an object, the corresponding element
- * styles are updated. Style names to update are taken from the object keys and values - from the
- * corresponding object values.
+ * An expression assigned to the `ng-style` property must evaluate to an object and the
+ * corresponding element styles are updated based on changes to this object. Style names to update
+ * are taken from the object's keys, and values - from the corresponding object's values.
  *
- * # Example:
+ * # Syntax
+ *
+ * - `<div [ng-style]="{'font-style': style}"></div>`
+ * - `<div [ng-style]="styleExp"></div>` - here the `styleExp` must evaluate to an object
+ *
+ * ### Example ([live demo](http://plnkr.co/edit/YamGS6GkUh9GqWNQhCyM?p=preview)):
  *
  * ```
- * <div [ng-style]="{'text-align': alignExp}"></div>
- * ```
+ * import {Component, View, NgStyle} from 'angular2/angular2';
  *
- * In the above example the `text-align` style will be updated based on the `alignExp` value
- * changes.
+ * @Component({
+ * selector: 'ng-style-example'
+ * })
+ * @View({
+ * template: `
+ * <h1 [ng-style]="{'font-style': style, 'font-size': size, 'font-weight': weight}">
+ * Change style of this text!
+ * </h1>
  *
- * # Syntax
+ * <hr>
+ *
+ * <label>Italic: <input type="checkbox" (change)="changeStyle($event)"></label>
+ * <label>Bold: <input type="checkbox" (change)="changeWeight($event)"></label>
+ * <label>Size: <input type="text" [value]="size" (change)="size = $event.target.value"></label>
+ * `,
+ * directives: [NgStyle]
+ * })
+ * export class NgStyleExample {
+ * style = 'normal';
+ * weight = 'normal';
+ * size = '20px';
+ *
+ * changeStyle($event: any) {
+ * this.style = $event.target.checked ? 'italic' : 'normal';
+ * }
+ *
+ * changeWeight($event: any) {
+ * this.weight = $event.target.checked ? 'bold' : 'normal';
+ * }
+ * }
+ * ```
  *
- * - `<div [ng-style]="{'text-align': alignExp}"></div>`
- * - `<div [ng-style]="styleExp"></div>`
+ * In this example the `font-style`, `font-size` and `font-weight` styles will be updated
+ * based on the `style` property's value changes.
  */
 @Directive({selector: '[ng-style]', inputs: ['rawStyle: ng-style']})
 export class NgStyle implements DoCheck {