docs: add api doc for switch directives (#27378)

PR Close #27378
2018-11-30 11:58:42 -08:00 · 2018-11-30 11:58:42 -08:00 · 850b86749c
parent a24120011e
commit 850b86749c
1 changed files with 81 additions and 47 deletions
--- a/packages/common/src/directives/ng_switch.ts
+++ b/packages/common/src/directives/ng_switch.ts
@ -36,9 +36,53 @@ export class SwitchView {
 /**
 * @ngModule CommonModule
 *
+ * @description A structural directive that adds or removes templates (displaying or hiding views)
+ * when the next match expression matches the switch expression.
+ *
+ * The `[ngSwitch]` directive on a container specifies an expression to match against.
+ * The expressions to match are provided by `ngSwitchCase` directives on views within the container.
+ * - Every view that matches is rendered.
+ * - If there are no matches, a view with the `ngSwitchDefault` directive is rendered.
+ * - Elements within the `[NgSwitch]` statement but outside of any `NgSwitchCase`
+ * or `ngSwitchDefault` directive are preserved at the location.
+ *
 * @usageNotes
+ * Define a container element for the directive, and specify the switch expression
+ * to match against as an attribute:
+ *
 * ```
- *     <container-element [ngSwitch]="switch_expression">
+ * <container-element [ngSwitch]="switch_expression">
+ * ```
+ *
+ * Within the container, `*ngSwitchCase` statements specify the match expressions
+ * as attributes. Include `*ngSwitchDefault` as the final case.
+ *
+ * ```
+ * <container-element [ngSwitch]="switch_expression">
+ *    <some-element *ngSwitchCase="match_expression_1">...</some-element>
+ * ...
+ *    <some-element *ngSwitchDefault>...</some-element>
+ * </container-element>
+ * ```
+ *
+ * ### Usage Examples
+ *
+ * The following example shows how to use more than one case to display the same view:
+ *
+ * ```
+ * <container-element [ngSwitch]="switch_expression">
+ *   <!-- the same view can be shown in more than one case -->
+ *   <some-element *ngSwitchCase="match_expression_1">...</some-element>
+ *   <some-element *ngSwitchCase="match_expression_2">...</some-element>
+ *   <some-other-element *ngSwitchCase="match_expression_3">...</some-other-element>
+ *   <!--default case when there are no matches -->
+ *   <some-element *ngSwitchDefault>...</some-element>
+ * </container-element>
+ * ```
+ *
+ * The following example shows how cases can be nested:
+ * ```
+ * <container-element [ngSwitch]="switch_expression">
 *       <some-element *ngSwitchCase="match_expression_1">...</some-element>
 *       <some-element *ngSwitchCase="match_expression_2">...</some-element>
 *       <some-other-element *ngSwitchCase="match_expression_3">...</some-other-element>
@ -50,28 +94,12 @@ export class SwitchView {
 *       <some-element *ngSwitchDefault>...</some-element>
 *     </container-element>
 * ```
- * @description
- *
- * Adds / removes DOM sub-trees when the nest match expressions matches the switch expression.
- *
- * `NgSwitch` stamps out nested views when their match expression value matches the value of the
- * switch expression.
- *
- * In other words:
- * - you define a container element (where you place the directive with a switch expression on the
- * `[ngSwitch]="..."` attribute)
- * - you define inner views inside the `NgSwitch` and place a `*ngSwitchCase` attribute on the view
- * root elements.
- *
- * Elements within `NgSwitch` but outside of a `NgSwitchCase` or `NgSwitchDefault` directives will
- * be preserved at the location.
- *
- * The `ngSwitchCase` directive informs the parent `NgSwitch` of which view to display when the
- * expression is evaluated.
- * When no matching expression is found on a `ngSwitchCase` view, the `ngSwitchDefault` view is
- * stamped out.
 *
 * @publicApi
+ * @see `NgSwitchCase`
+ * @see `NgSwitchDefault`
+ * @see [Stuctural Directives](guide/structural-directives)
+ *
 */
@Directive({selector: '[ngSwitch]'})
 export class NgSwitch {
@ -129,31 +157,42 @@ export class NgSwitch {
 /**
 * @ngModule CommonModule
 *
+ * @description
+ * Provides a switch case expression to match against an enclosing `ngSwitch` expression.
+ * When the expressions match, the given `NgSwitchCase` template is rendered.
+ * If multiple match expressions match the switch expression value, all of them are displayed.
+ *
 * @usageNotes
+ *
+ * Within a switch container, `*ngSwitchCase` statements specify the match expressions
+ * as attributes. Include `*ngSwitchDefault` as the final case.
+ *
 * ```
 * <container-element [ngSwitch]="switch_expression">
 *   <some-element *ngSwitchCase="match_expression_1">...</some-element>
+ *   ...
+ *   <some-element *ngSwitchDefault>...</some-element>
 * </container-element>
- *```
- * @description
+ * ```
 *
- * Creates a view that will be added/removed from the parent {@link NgSwitch} when the
- * given expression evaluate to respectively the same/different value as the switch
- * expression.
+ * Each switch-case statement contains an in-line HTML template or template reference
+ * that defines the subtree to be selected if the value of the match expression
+ * matches the value of the switch expression.
 *
- * Insert the sub-tree when the expression evaluates to the same value as the enclosing switch
- * expression.
- *
- * If multiple match expressions match the switch expression value, all of them are displayed.
- *
- * See {@link NgSwitch} for more details and example.
+ * Unlike JavaScript, which uses strict equality, Angular uses loose equality.
+ * This means that the empty string, `""` matches 0.
 *
 * @publicApi
+ * @see `NgSwitch`
+ * @see `NgSwitchDefault`
+ *
 */
@Directive({selector: '[ngSwitchCase]'})
 export class NgSwitchCase implements DoCheck {
  private _view: SwitchView;
-
+  /**
+   * Stores the HTML template to be selected on match.
+   */
  @Input()
  ngSwitchCase: any;

@ -164,30 +203,25 @@ export class NgSwitchCase implements DoCheck {
    this._view = new SwitchView(viewContainer, templateRef);
  }

+  /**
+   * Performs case matching. For internal use only.
+   */
  ngDoCheck() { this._view.enforceState(this.ngSwitch._matchCase(this.ngSwitchCase)); }
 }

 /**
 * @ngModule CommonModule
- * @usageNotes
- * ```
- * <container-element [ngSwitch]="switch_expression">
- *   <some-element *ngSwitchCase="match_expression_1">...</some-element>
- *   <some-other-element *ngSwitchDefault>...</some-other-element>
- * </container-element>
- * ```
 *
 * @description
 *
- * Creates a view that is added to the parent {@link NgSwitch} when no case expressions
- * match the switch expression.
- *
- * Insert the sub-tree when no case expressions evaluate to the same value as the enclosing switch
- * expression.
- *
- * See {@link NgSwitch} for more details and example.
+ * Creates a view that is rendered when no `NgSwitchCase` expressions
+ * match the `NgSwitch` expression.
+ * This statement should be the final case in an `NgSwitch`.
 *
 * @publicApi
+ * @see `NgSwitch`
+ * @see `NgSwitchCase`
+ *
 */
@Directive({selector: '[ngSwitchDefault]'})
 export class NgSwitchDefault {