docs(forms): add example app for formControlDirective (#11508)

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

@@ -24,51 +24,44 @@ export const formControlBinding: any = {
 };
 
 /**
- * Binds an existing {@link FormControl} to a DOM element. It requires importing the {@link
- * ReactiveFormsModule}.
+ * @whatItDoes Syncs a standalone {@link FormControl} instance to a form control element.
  *
- * In this example, we bind the control to an input element. When the value of the input element
- * changes, the value of the control will reflect that change. Likewise, if the value of the
- * control changes, the input element reflects that change.
+ * In other words, this directive ensures that any values written to the {@link FormControl}
+ * instance programmatically will be written to the DOM element (model -> view). Conversely,
+ * any values written to the DOM element through user input will be reflected in the
+ * {@link FormControl} instance (view -> model).
  *
- *  ```typescript
- * @Component({
- *   selector: 'my-app',
- *   template: `
- *     <div>
- *       <h2>Bind existing control example</h2>
- *       <form>
- *         <p>Element with existing control: <input type="text"
- * [formControl]="loginControl"></p>
- *         <p>Value of existing control: {{loginControl.value}}</p>
- *       </form>
- *     </div>
- *   `,
- * })
- * export class App {
- *   loginControl: FormControl = new FormControl('');
- * }
- *  ```
+ * @howToUse
  *
- * ### ngModel
+ * Use this directive if you'd like to create and manage a {@link FormControl} instance directly.
+ * Simply create a {@link FormControl}, save it to your component class, and pass it into the
+ * {@link FormControlDirective}.
  *
- * We can also set the value of the form programmatically with setValue().
- **
- *  ```typescript
- * @Component({
- *      selector: "login-comp",
-
- *      template: "<input type='text' [formControl]='loginControl'>"
- *      })
- * class LoginComp {
- *  loginControl: FormControl = new FormControl('');
+ * This directive is designed to be used as a standalone control.  Unlike {@link FormControlName},
+ * it does not require that your {@link FormControl} instance be part of any parent
+ * {@link FormGroup}, and it won't be registered to any {@link FormGroupDirective} that
+ * exists above it.
  *
- *  populate() {
- *    this.loginControl.setValue('some login');
- *  }
+ * **Get the value**: the `value` property is always synced and available on the
+ * {@link FormControl} instance. See a full list of available properties in
+ * {@link AbstractControl}.
  *
- * }
- *  ```
+ * **Set the value**: You can pass in an initial value when instantiating the {@link FormControl},
+ * or you can set it programmatically later using {@link AbstractControl.setValue} or
+ * {@link AbstractControl.patchValue}.
+ *
+ * **Listen to value**: If you want to listen to changes in the value of the control, you can
+ * subscribe to the {@link AbstractControl.valueChanges} event.  You can also listen to
+ * {@link AbstractControl.statusChanges} to be notified when the validation status is
+ * re-calculated.
+ *
+ * ### Example
+ *
+ * {@example forms/ts/simpleFormControl/simple_form_control_example.ts region='Component'}
+ *
+ * * **npm package**: `@angular/forms`
+ *
+ * * **NgModule**: `ReactiveFormsModule`
  *
  *  @stable
  */