docs(forms): add example app for formArrayName (#11512)

modules/@angular/forms/src/directives/reactive_directives/form_group_name.ts

@@ -95,38 +95,49 @@ export const formArrayNameProvider: any = {
 };
 
 /**
- * Syncs an existing form array to a DOM element.
+ * @whatItDoes Syncs a nested {@link FormArray} to a DOM element.
  *
- * This directive can only be used as a child of {@link FormGroupDirective}.  It also requires
- * importing the {@link ReactiveFormsModule}.
+ * @howToUse
  *
- * ```typescript
- * @Component({
- *   selector: 'my-app',
- *   template: `
- *     <div>
- *       <h2>Angular FormArray Example</h2>
- *       <form [formGroup]="myForm">
- *         <div formArrayName="cities">
- *           <div *ngFor="let city of cityArray.controls; let i=index">
- *             <input [formControlName]="i">
- *           </div>
- *         </div>
- *       </form>
- *       {{ myForm.value | json }}     // {cities: ['SF', 'NY']}
- *     </div>
- *   `
- * })
- * export class App {
- *   cityArray = new FormArray([
- *     new FormControl('SF'),
- *     new FormControl('NY')
- *   ]);
- *   myForm = new FormGroup({
- *     cities: this.cityArray
- *   });
- * }
- * ```
+ * This directive is designed to be used with a parent {@link FormGroupDirective} (selector:
+ * `[formGroup]`).
+ *
+ * It accepts the string name of the nested {@link FormArray} you want to link, and
+ * will look for a {@link FormArray} registered with that name in the parent
+ * {@link FormGroup} instance you passed into {@link FormGroupDirective}.
+ *
+ * Nested form arrays can come in handy when you have a group of form controls but
+ * you're not sure how many there will be. Form arrays allow you to create new
+ * form controls dynamically.
+ *
+ * **Access the array**: You can access the associated {@link FormArray} using the
+ * {@link AbstractControl.get} method on the parent {@link FormGroup}.
+ * Ex: `this.form.get('cities')`.
+ *
+ * **Get the value**: the `value` property is always synced and available on the
+ * {@link FormArray}. See a full list of available properties in {@link AbstractControl}.
+ *
+ * **Set the value**: You can set an initial value for each child control when instantiating
+ * the {@link FormArray}, or you can set the value programmatically later using the
+ * {@link FormArray}'s {@link AbstractControl.setValue} or {@link AbstractControl.patchValue}
+ * methods.
+ *
+ * **Listen to value**: If you want to listen to changes in the value of the array, you can
+ * subscribe to the {@link FormArray}'s {@link AbstractControl.valueChanges} event.  You can also
+ * listen to its {@link AbstractControl.statusChanges} event to be notified when the validation
+ * status is re-calculated.
+ *
+ * **Add new controls**: You can add new controls to the {@link FormArray} dynamically by
+ * calling its {@link FormArray.push} method.
+ *  Ex: `this.form.get('cities').push(new FormControl());`
+ *
+ * ### Example
+ *
+ * {@example forms/ts/nestedFormArray/nested_form_array_example.ts region='Component'}
+ *
+ * * **npm package**: `@angular/forms`
+ *
+ * * **NgModule**: `ReactiveFormsModule`
  *
  * @stable
  */