docs(forms): add example app for formControlName

modules/@angular/examples/forms/ts/formControlName/e2e_test/form_control_name_spec.ts

@@ -0,0 +1,38 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {verifyNoBrowserErrors} from '../../../../_common/e2e_util';
+
+describe('formControlName example', () => {
+  afterEach(verifyNoBrowserErrors);
+
+  describe('index view', () => {
+    let firstInput: ElementFinder;
+    let lastInput: ElementFinder;
+
+    beforeEach(() => {
+      browser.get('/forms/ts/formControlName/index.html');
+      firstInput = element(by.css('[formControlName="first"]'));
+      lastInput = element(by.css('[formControlName="last"]'));
+    });
+
+    it('should populate the form control values in the DOM', () => {
+      expect(firstInput.getAttribute('value')).toEqual('Nancy');
+      expect(lastInput.getAttribute('value')).toEqual('Drew');
+    });
+
+    it('should show the error when the form is invalid', () => {
+      firstInput.click();
+      firstInput.clear();
+      firstInput.sendKeys('a');
+
+      expect(element(by.css('div')).getText()).toEqual('Name is too short.');
+    });
+
+  });
+});

modules/@angular/examples/forms/ts/formControlName/form_control_name_example.ts

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+// #docregion Component
+import {Component} from '@angular/core';
+import {FormControl, FormGroup, Validators} from '@angular/forms';
+
+@Component({
+  selector: 'example-app',
+  template: `
+    <form [formGroup]="form" (ngSubmit)="onSubmit()">
+      <div *ngIf="first.invalid"> Name is too short. </div>
+      
+      <input formControlName="first" placeholder="First name">
+      <input formControlName="last" placeholder="Last name">
+      
+      <button type="submit">Submit</button>
+   </form>
+  
+  `
+})
+export class FormControlNameComp {
+  form = new FormGroup(
+      {first: new FormControl('Nancy', Validators.minLength(2)), last: new FormControl('Drew')});
+
+  get first() { return this.form.get('first'); }
+
+  onSubmit(): void {
+    console.log(this.form.value);  // {first: 'Nancy', last: 'Drew'}
+  }
+}
+
+
+// #enddocregion

modules/@angular/examples/forms/ts/formControlName/module.ts

@@ -0,0 +1,20 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {NgModule} from '@angular/core';
+import {ReactiveFormsModule} from '@angular/forms';
+import {BrowserModule} from '@angular/platform-browser';
+import {FormControlNameComp} from './form_control_name_example';
+
+@NgModule({
+  imports: [BrowserModule, ReactiveFormsModule],
+  declarations: [FormControlNameComp],
+  bootstrap: [FormControlNameComp]
+})
+export class AppModule {
+}

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

@@ -28,69 +28,37 @@ export const controlNameBinding: any = {
 };
 
 /**
- * Syncs an existing form control with the specified name to a DOM element.
+ * @whatItDoes  Syncs a form control element to an existing {@link FormControl} instance by name.
+ *
+ * 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).
+ *
+ * @howToUse
+ *
+ * This directive must be used with a parent {@link FormGroupDirective} (selector: `[formGroup]`).
+ *
+ * Pass in the string name of the {@link FormControl} instance you want to link. It will look for a
+ * control registered with that name in the {@link FormGroup} passed to the parent
+ * {@link FormGroupDirective}.
+ *
+ *  You can initialize the value of the form when instantiating the {@link FormGroup}, or you can
+ * set it programmatically later using {@link AbstractControl.setValue} or
+ * {@link AbstractControl.patchValue}.
+ *
+ * If you want to listen to changes in the value of the form, you can subscribe to the
+ * {@link AbstractControl.valueChanges} event.
  *
- * This directive can only be used as a child of {@link FormGroupDirective}.  It also requires
- * importing the {@link ReactiveFormsModule}.
-
  * ### Example
  *
- * In this example, we create the login and password controls.
- * We can work with each control separately: check its validity, get its value, listen to its
- * changes.
+ * In this example, we create form controls for first name and last name.
  *
- *  ```
- * @Component({
- *      selector: "login-comp",
- *      template: `
- *        <form [formGroup]="myForm" (submit)="onLogIn()">
- *          Login <input type="text" formControlName="login">
- *          <div *ngIf="!loginCtrl.valid">Login is invalid</div>
- *          Password <input type="password" formControlName="password">
- *          <button type="submit">Log in!</button>
- *        </form>
- *      `})
- * class LoginComp {
- *  loginCtrl = new FormControl();
- *  passwordCtrl = new FormControl();
- *  myForm = new FormGroup({
- *     login: loginCtrl,
- *     password: passwordCtrl
- *  });
- *  onLogIn(): void {
- *    // value === {login: 'some login', password: 'some password'}
- *  }
- * }
- *  ```
+ * {@example forms/ts/formControlName/form_control_name_example.ts region='Component'}
  *
- * We can also set the value of the form programmatically using setValue().
+ *  * **npm package**: `@angular/forms`
  *
- *  ```
- * @Component({
- *      selector: "login-comp",
- *      template: `
- *        <form [formGroup]="myForm" (submit)='onLogIn()'>
- *          Login <input type='text' formControlName='login'>
- *          Password <input type='password' formControlName='password'>
- *          <button type='submit'>Log in!</button>
- *        </form>
- *      `})
- * class LoginComp {
- *  myForm = new FormGroup({
- *    login: new FormControl(),
- *    password: new FormControl()
- *  });
- *
- *  populate() {
- *     this.myForm.setValue({login: 'some login', password: 'some password'});
- *  }
- *
- *  onLogIn(): void {
- *    // this.credentials.login === "some login"
- *    // this.credentials.password === "some password"
- *  }
- * }
- *  ```
+ *  * **NgModule**: {@link ReactiveFormsModule}
  *
  *  @stable
  */