doc(NgSwitch): update API doc

vicb · vicb · commit 857bef9e4fad · 2015-11-17T00:54:32.000Z
Closes angular#4423
diff --git a/modules/angular2/src/common/directives/ng_switch.ts b/modules/angular2/src/common/directives/ng_switch.ts
@@ -6,7 +6,7 @@ import {ListWrapper, Map} from 'angular2/src/facade/collection';
 
 const _WHEN_DEFAULT = CONST_EXPR(new Object());
 
-export class SwitchView {
+class SwitchView {
   constructor(private _viewContainerRef: ViewContainerRef, private _templateRef: TemplateRef) {}
 
   create(): void { this._viewContainerRef.createEmbeddedView(this._templateRef); }
@@ -15,28 +15,59 @@ export class SwitchView {
 }
 
 /**
- * The `NgSwitch` directive is used to conditionally swap DOM structure on your template based on a
- * scope expression.
+ * Adds or removes DOM sub-trees when their match expressions match the switch expression.
+ *
  * Elements within `NgSwitch` but without `NgSwitchWhen` or `NgSwitchDefault` directives will be
  * preserved at the location as specified in the template.
  *
- * `NgSwitch` simply chooses nested elements and makes them visible based on which element matches
- * the value obtained from the evaluated expression. In other words, you define a container element
- * (where you place the directive), place an expression on the **`[ng-switch]="..."` attribute**),
- * define any inner elements inside of the directive and place a `[ng-switch-when]` attribute per
- * element.
- * The when attribute is used to inform NgSwitch which element to display when the expression is
- * evaluated. If a matching expression is not found via a when attribute then an element with the
- * default attribute is displayed.
+ * `NgSwitch` simply inserts nested elements based on which match expression matches the value
+ * obtained from the evaluated switch expression. In other words, you define a container element
+ * (where you place the directive with a switch expression on the
+ * **`[ng-switch]="..."` attribute**), define any inner elements inside of the directive and
+ * place a `[ng-switch-when]` attribute per element.
  *
- * ### Example
+ * The `ng-switch-when` property is used to inform `NgSwitch` which element to display when the
+ * expression is evaluated. If a matching expression is not found via a `ng-switch-when` property
+ * then an element with the `ng-switch-default` attribute is displayed.
  *
- * ```
- * <ANY [ng-switch]="expression">
- *   <template [ng-switch-when]="whenExpression1">...</template>
- *   <template [ng-switch-when]="whenExpression1">...</template>
- *   <template ng-switch-default>...</template>
- * </ANY>
+ * ### Example ([live demo](http://plnkr.co/edit/DQMTII95CbuqWrl3lYAs?p=preview))
+ *
+ * ```typescript
+ * @Component({selector: 'app'})
+ * @View({
+ *   template: `
+ *     <p>Value = {{value}}</p>
+ *     <button (click)="inc()">Increment</button>
+ *
+ *     <div [ng-switch]="value">
+ *       <p *ng-switch-when="'init'">increment to start</p>
+ *       <p *ng-switch-when="0">0, increment again</p>
+ *       <p *ng-switch-when="1">1, increment again</p>
+ *       <p *ng-switch-when="2">2, stop incrementing</p>
+ *       <p *ng-switch-default>&gt; 2, STOP!</p>
+ *     </div>
+ *
+ *     <!-- alternate syntax -->
+ *
+ *     <p [ng-switch]="value">
+ *       <template ng-switch-when="init">increment to start</template>
+ *       <template [ng-switch-when]="0">0, increment again</template>
+ *       <template [ng-switch-when]="1">1, increment again</template>
+ *       <template [ng-switch-when]="2">2, stop incrementing</template>
+ *       <template ng-switch-default>&gt; 2, STOP!</template>
+ *     </p>
+ *   `,
+ *   directives: [NgSwitch, NgSwitchWhen, NgSwitchDefault]
+ * })
+ * export class App {
+ *   value = 'init';
+ *
+ *   inc() {
+ *     this.value = this.value === 'init' ? 0 : this.value + 1;
+ *   }
+ * }
+ *
+ * bootstrap(App).catch(err => console.error(err));
  * ```
  */
 @Directive({selector: '[ng-switch]', inputs: ['ngSwitch']})
@@ -130,19 +161,12 @@ export class NgSwitch {
 }
 
 /**
- * Defines a case statement as an expression.
+ * Insert the sub-tree when the `ng-switch-when` expression evaluates to the same value as the
+ * enclosing switch expression.
  *
- * If multiple `NgSwitchWhen` match the `NgSwitch` value, all of them are displayed.
+ * If multiple match expression match the switch expression value, all of them are displayed.
  *
- * Example:
- *
- * ```
- * // match against a context variable
- * <template [ng-switch-when]="contextVariable">...</template>
- *
- * // match against a constant string
- * <template ng-switch-when="stringValue">...</template>
- * ```
+ * See {@link NgSwitch} for more details and example.
  */
 @Directive({selector: '[ng-switch-when]', inputs: ['ngSwitchWhen']})
 export class NgSwitchWhen {
@@ -151,9 +175,11 @@ export class NgSwitchWhen {
   _value: any = _WHEN_DEFAULT;
   /** @internal */
   _view: SwitchView;
+  private _switch: NgSwitch;
 
   constructor(viewContainer: ViewContainerRef, templateRef: TemplateRef,
-              @Host() private _switch: NgSwitch) {
+              @Host() ngSwitch: NgSwitch) {
+    this._switch = ngSwitch;
     this._view = new SwitchView(viewContainer, templateRef);
   }
 
@@ -164,15 +190,10 @@ export class NgSwitchWhen {
 }
 
 /**
- * Defines a default case statement.
+ * Default case statements are displayed when no match expression matches the switch expression
+ * value.
  *
- * Default case statements are displayed when no `NgSwitchWhen` match the `ng-switch` value.
- *
- * Example:
- *
- * ```
- * <template ng-switch-default>...</template>
- * ```
+ * See {@link NgSwitch} for more details and example.
  */
 @Directive({selector: '[ng-switch-default]'})
 export class NgSwitchDefault {
