diff --git a/modules/@angular/examples/forms/ts/formControlName/e2e_test/form_control_name_spec.ts b/modules/@angular/examples/forms/ts/formControlName/e2e_test/form_control_name_spec.ts
new file mode 100644
index 0000000000..97dbe4e877
--- /dev/null
+++ b/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.');
+ });
+
+ });
+});
diff --git a/modules/@angular/examples/forms/ts/formControlName/form_control_name_example.ts b/modules/@angular/examples/forms/ts/formControlName/form_control_name_example.ts
new file mode 100644
index 0000000000..9ed77c7a6e
--- /dev/null
+++ b/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: `
+
+
+ `
+})
+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
diff --git a/modules/@angular/examples/forms/ts/formControlName/module.ts b/modules/@angular/examples/forms/ts/formControlName/module.ts
new file mode 100644
index 0000000000..4f1924e677
--- /dev/null
+++ b/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 {
+}
diff --git a/modules/@angular/forms/src/directives/reactive_directives/form_control_name.ts b/modules/@angular/forms/src/directives/reactive_directives/form_control_name.ts
index 184d9c7160..5ab82c88a1 100644
--- a/modules/@angular/forms/src/directives/reactive_directives/form_control_name.ts
+++ b/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: `
- *
- * `})
- * 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: `
- *
- * `})
- * 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
*/