docs(common): add directives docs

Closes #11581

modules/@angular/common/src/directives/ng_plural.ts

@@ -14,48 +14,35 @@ import {SwitchView} from './ng_switch';
 
 
 /**
- * `ngPlural` is an i18n directive that displays DOM sub-trees that match the switch expression
- * value, or failing that, DOM sub-trees that match the switch expression's pluralization category.
+ * @ngModule CommonModule
+ *
+ * @whatItDoes Adds / removes DOM sub-trees based on a numeric value. Tailored for pluralization.
+ *
+ * @howToUse
+ * ```
+ * <some-element [ngPlural]="value">
+ *   <ng-container *ngPluralCase="'=0'">there is nothing</ng-container>
+ *   <ng-container *ngPluralCase="'=1'">there is one</ng-container>
+ *   <ng-container *ngPluralCase="'few'">there are a few</ng-container>
+ *   <ng-container *ngPluralCase="'other'">there are exactly #</ng-container>
+ * </some-element>
+ * ```
+ *
+ * @description
+ *
+ * Displays DOM sub-trees that match the switch expression value, or failing that, DOM sub-trees
+ * that match the switch expression's pluralization category.
  *
  * To use this directive you must provide a container element that sets the `[ngPlural]` attribute
- * to a
- * switch expression.
- *    - Inner elements defined with an `[ngPluralCase]` attribute will display based on their
- * expression.
- *    - If `[ngPluralCase]` is set to a value starting with `=`, it will only display if the value
- * matches the switch expression exactly.
- *    - Otherwise, the view will be treated as a "category match", and will only display if exact
- * value matches aren't found and the value maps to its category for the defined locale.
+ * to a switch expression. Inner elements with a `[ngPluralCase]` will display based on their
+ * expression:
+ * - if `[ngPluralCase]` is set to a value starting with `=`, it will only display if the value
+ *   matches the switch expression exactly,
+ * - otherwise, the view will be treated as a "category match", and will only display if exact
+ *   value matches aren't found and the value maps to its category for the defined locale.
  *
- * ```typescript
- * @Component({
- *    selector: 'app',
- *    // best practice is to define the locale at the application level
- *    providers: [{provide: LOCALE_ID, useValue: 'en_US'}]
- * })
- * @View({
- *   template: `
- *     <p>Value = {{value}}</p>
- *     <button (click)="inc()">Increment</button>
+ * See http://cldr.unicode.org/index/cldr-spec/plural-rules
  *
- *     <div [ngPlural]="value">
- *       <template ngPluralCase="=0">there is nothing</template>
- *       <template ngPluralCase="=1">there is one</template>
- *       <template ngPluralCase="few">there are a few</template>
- *       <template ngPluralCase="other">there is some number</template>
- *     </div>
- *   `,
- *   directives: [NgPlural, NgPluralCase]
- * })
- * export class App {
- *   value = 'init';
- *
- *   inc() {
- *     this.value = this.value === 'init' ? 0 : this.value + 1;
- *   }
- * }
- *
- * ```
  * @experimental
  */
 @Directive({selector: '[ngPlural]'})
@@ -98,6 +85,19 @@ export class NgPlural {
 }
 
 /**
+ * @ngModule CommonModule
+ *
+ * @whatItDoes Creates a view that will be added/removed from the parent {@link NgPlural} when the
+ *             given expression matches the plural expression according to CLDR rules.
+ *
+ * @howToUse
+ *     <some-element [ngPlural]="value">
+ *       <ng-container *ngPluralCase="'=0'">...</ng-container>
+ *       <ng-container *ngPluralCase="'other'">...</ng-container>
+ *     </some-element>
+ *
+ * See {@link NgPlural} for more details and example.
+ *
  * @experimental
  */
 @Directive({selector: '[ngPluralCase]'})