docs(ngForm): fix grammar and improve explanation

jdavisp3 · petebacondarwin · commit f363bcb4376b · 2013-09-19T10:41:30.000+01:00
Closes angular#4050
diff --git a/src/ng/directive/form.js b/src/ng/directive/form.js
@@ -188,15 +188,19 @@ function FormController(element, attrs) {
  * Directive that instantiates
  * {@link ng.directive:form.FormController FormController}.
  *
- * If `name` attribute is specified, the form controller is published onto the current scope under
+ * If the `name` attribute is specified, the form controller is published onto the current scope under
  * this name.
  *
  * # Alias: {@link ng.directive:ngForm `ngForm`}
  *
- * In angular forms can be nested. This means that the outer form is valid when all of the child
- * forms are valid as well. However browsers do not allow nesting of `<form>` elements, for this
- * reason angular provides {@link ng.directive:ngForm `ngForm`} alias
- * which behaves identical to `<form>` but allows form nesting.
+ * In Angular forms can be nested. This means that the outer form is valid when all of the child
+ * forms are valid as well. However, browsers do not allow nesting of `<form>` elements, so
+ * Angular provides the {@link ng.directive:ngForm `ngForm`} directive which behaves identically to
+ * `<form>` but can be nested.  This allows you to have nested forms, which is very useful when
+ * using Angular validation directives in forms that are dynamically generated using the
+ * {@link ng.directive:ngRepeat `ngRepeat`} directive. Since you cannot dynamically generate the `name`
+ * attribute of input elements using interpolation, you have to wrap each set of repeated inputs in an
+ * `ngForm` directive and nest these in an outer `form` element.
  *
  *
  * # CSS classes
@@ -206,12 +210,12 @@ function FormController(element, attrs) {
  *  - `ng-dirty` Is set if the form is dirty.
  *
  *
- * # Submitting a form and preventing default action
+ * # Submitting a form and preventing the default action
  *
  * Since the role of forms in client-side Angular applications is different than in classical
  * roundtrip apps, it is desirable for the browser not to translate the form submission into a full
  * page reload that sends the data to the server. Instead some javascript logic should be triggered
- * to handle the form submission in application specific way.
+ * to handle the form submission in an application-specific way.
  *
  * For this reason, Angular prevents the default action (form submission to the server) unless the
  * `<form>` element has an `action` attribute specified.
@@ -223,8 +227,9 @@ function FormController(element, attrs) {
  * - {@link ng.directive:ngClick ngClick} directive on the first
   *  button or input field of type submit (input[type=submit])
  *
- * To prevent double execution of the handler, use only one of ngSubmit or ngClick directives. This
- * is because of the following form submission rules coming from the html spec:
+ * To prevent double execution of the handler, use only one of the {@link ng.directive:ngSubmit ngSubmit}
+ * or {@link ng.directive:ngClick ngClick} directives.
+ * This is because of the following form submission rules in the HTML specification:
  *
  * - If a form has only one input field then hitting enter in this field triggers form submit
  * (`ngSubmit`)

Original file line number	Diff line number	Diff line change
`@@ -188,15 +188,19 @@ function FormController(element, attrs) {`
`188`	`188`	`* Directive that instantiates`
`189`	`189`	`* {@link ng.directive:form.FormController FormController}.`
`190`	`190`	`*`
`191`		- * If `name` attribute is specified, the form controller is published onto the current scope under
	`191`	+ * If the `name` attribute is specified, the form controller is published onto the current scope under
`192`	`192`	`* this name.`
`193`	`193`	`*`
`194`	`194`	* # Alias: {@link ng.directive:ngForm `ngForm`}
`195`	`195`	`*`
`196`		`- * In angular forms can be nested. This means that the outer form is valid when all of the child`
`197`		- * forms are valid as well. However browsers do not allow nesting of `<form>` elements, for this
`198`		- * reason angular provides {@link ng.directive:ngForm `ngForm`} alias
`199`		- * which behaves identical to `<form>` but allows form nesting.
	`196`	`+ * In Angular forms can be nested. This means that the outer form is valid when all of the child`
	`197`	+ * forms are valid as well. However, browsers do not allow nesting of `<form>` elements, so
	`198`	+ * Angular provides the {@link ng.directive:ngForm `ngForm`} directive which behaves identically to
	`199`	+ * `<form>` but can be nested. This allows you to have nested forms, which is very useful when
	`200`	`+ * using Angular validation directives in forms that are dynamically generated using the`
	`201`	+ * {@link ng.directive:ngRepeat `ngRepeat`} directive. Since you cannot dynamically generate the `name`
	`202`	`+ * attribute of input elements using interpolation, you have to wrap each set of repeated inputs in an`
	`203`	+ * `ngForm` directive and nest these in an outer `form` element.
`200`	`204`	`*`
`201`	`205`	`*`
`202`	`206`	`* # CSS classes`
`@@ -206,12 +210,12 @@ function FormController(element, attrs) {`
`206`	`210`	* - `ng-dirty` Is set if the form is dirty.
`207`	`211`	`*`
`208`	`212`	`*`
`209`		`- * # Submitting a form and preventing default action`
	`213`	`+ * # Submitting a form and preventing the default action`
`210`	`214`	`*`
`211`	`215`	`* Since the role of forms in client-side Angular applications is different than in classical`
`212`	`216`	`* roundtrip apps, it is desirable for the browser not to translate the form submission into a full`
`213`	`217`	`* page reload that sends the data to the server. Instead some javascript logic should be triggered`
`214`		`- * to handle the form submission in application specific way.`
	`218`	`+ * to handle the form submission in an application-specific way.`
`215`	`219`	`*`
`216`	`220`	`* For this reason, Angular prevents the default action (form submission to the server) unless the`
`217`	`221`	* `<form>` element has an `action` attribute specified.
`@@ -223,8 +227,9 @@ function FormController(element, attrs) {`
`223`	`227`	`* - {@link ng.directive:ngClick ngClick} directive on the first`
`224`	`228`	`* button or input field of type submit (input[type=submit])`
`225`	`229`	`*`
`226`		`- * To prevent double execution of the handler, use only one of ngSubmit or ngClick directives. This`
`227`		`- * is because of the following form submission rules coming from the html spec:`
	`230`	`+ * To prevent double execution of the handler, use only one of the {@link ng.directive:ngSubmit ngSubmit}`
	`231`	`+ * or {@link ng.directive:ngClick ngClick} directives.`
	`232`	`+ * This is because of the following form submission rules in the HTML specification:`
`228`	`233`	`*`
`229`	`234`	`* - If a form has only one input field then hitting enter in this field triggers form submit`
`230`	`235`	* (`ngSubmit`)