docs(forms): update docs for NgForm (#11547)

modules/@angular/examples/forms/ts/simpleForm/simple_form_example.ts

@@ -14,8 +14,8 @@ import {NgForm} from '@angular/forms';
   selector: 'example-app',
   template: `
     <form #f="ngForm" (ngSubmit)="onSubmit(f)" novalidate>
-      <input name="first" ngModel placeholder="First name" required #first="ngModel">
-      <input name="last" ngModel placeholder="Last name">
+      <input name="first" ngModel required #first="ngModel">
+      <input name="last" ngModel>
       <button>Submit</button>
     </form>
     

modules/@angular/forms/src/directives/ng_form.ts

@@ -29,61 +29,32 @@ export const formDirectiveProvider: any = {
 const resolvedPromise = Promise.resolve(null);
 
 /**
- * If `NgForm` is bound in a component, `<form>` elements in that component will be
- * upgraded to use the Angular form system.
+ * @whatItDoes Creates a top-level {@link FormGroup} instance and binds it to a form
+ * to track aggregate form value and validation status.
  *
- * ### Typical Use
+ * @howToUse
  *
- * Include `FORM_DIRECTIVES` in the `directives` section of a {@link Component} annotation
- * to use `NgForm` and its associated controls.
+ * As soon as you import the `FormsModule`, this directive becomes active by default on
+ * all `<form>` tags.  You don't need to add a special selector.
  *
- * ### Structure
+ * You can export the directive into a local template variable using `ngForm` as the key
+ * (ex: `#myForm="ngForm"`). This is optional, but useful.  Many properties from the underlying
+ * {@link FormGroup} instance are duplicated on the directive itself, so a reference to it
+ * will give you access to the aggregate value and validity status of the form, as well as
+ * user interaction properties like `dirty` and `touched`.
  *
- * An Angular form is a collection of `FormControl`s in some hierarchy.
- * `FormControl`s can be at the top level or can be organized in `FormGroup`s
- * or `FormArray`s. This hierarchy is reflected in the form's `value`, a
- * JSON object that mirrors the form structure.
+ * To register child controls with the form, you'll want to use {@link NgModel} with a
+ * `name` attribute.  You can also use {@link NgModelGroup} if you'd like to create
+ * sub-groups within the form.
  *
- * ### Submission
+ * You can listen to the directive's `ngSubmit` event to be notified when the user has
+ * triggered a form submission.
  *
- * The `ngSubmit` event signals when the user triggers a form submission.
+ * {@example forms/ts/simpleForm/simple_form_example.ts region='Component'}
  *
- *  ```typescript
- * @Component({
- *   selector: 'my-app',
- *   template: `
- *     <div>
- *       <p>Submit the form to see the data object Angular builds</p>
- *       <h2>NgForm demo</h2>
- *       <form #f="ngForm" (ngSubmit)="onSubmit(f.value)">
- *         <h3>Control group: credentials</h3>
- *         <div ngModelGroup="credentials">
- *           <p>Login: <input type="text" name="login" ngModel></p>
- *           <p>Password: <input type="password" name="password" ngModel></p>
- *         </div>
- *         <h3>Control group: person</h3>
- *         <div ngModelGroup="person">
- *           <p>First name: <input type="text" name="firstName" ngModel></p>
- *           <p>Last name: <input type="text" name="lastName" ngModel></p>
- *         </div>
- *         <button type="submit">Submit Form</button>
- *       <p>Form data submitted:</p>
- *       </form>
- *       <pre>{{data}}</pre>
- *     </div>
- * `,
- *   directives: []
- * })
- * export class App {
- *   constructor() {}
+ * * **npm package**: `@angular/forms`
  *
- *   data: string;
- *
- *   onSubmit(data) {
- *     this.data = JSON.stringify(data, null, 2);
- *   }
- * }
- *  ```
+ * * **NgModule**: `FormsModule`
  *
  *  @stable
  */