Form API topic in form.inc is really out of date

Reference: https://drupal.org/node/2117411

Thanks! This looks mostly excellent! A few proofreading-type things to fix:

a) Whenever you refer to a namespaced class in docs, it needs to start with \. For example:

+ * Forms are defined as classes that implement the Drupal\Core\Form\FormInterface
+ * and are built using the Drupal\Core\Form\FormBuilder class. Drupal provides a

in both lines it should be \Drupal\Core\....

b) Pet grammar/puncutation peeve [I had a postdoc advisor who was a stickler for this, "some years ago"]:

...
+ * couple of utility classes which can be extended as a starting point for most
...

You either need to change "which" to "that", or precede it by a comma. The only exception would be in "of which".

c)

+ * and are built using the Drupal\Core\Form\FormBuilder class. Drupal provides a
+ * couple of utility classes which can be extended as a starting point for most
+ * basic forms the most commonly used of which is Drupal\Core\Form\FormBase.

In that 3rd line, I think a comma after "forms" would be helpful? Or a semicolon, which would let you make a complete sentence for the 2nd clause, and completely remove the "of which" there? Check the rest of the patch too -- a couple of other spots.

d)

+ * FormBuilder handles the low level processing of forms such as rendering the
+ * necessary HTML, initial processing of incoming $_POST data and delegating to
+ * your implementation of FormInterface for validation and processing of
+ * submitted data.

Oxford comma -- in a list of "a, b, and c" or "a, b, or c", we require a comma before the "and" or "or" [here, the "and" on the 2nd line]. Also do you think a comma would be helpful before "such as" in the first line?

e)

+ * \Drupal::formBuilder()->getForm() should be used to handle retrieving,
+ * processing, and displaying a rendered HTML form.
+ *
+ * Here is an example of how to use \Drupal::formBuilder()->getForm() and a form
+ * class:

I'd make these into one paragraph? Also, in the example code that follows, there is no call to ->getForm(). I think I'd just add a line (after a blank line) at the end with that call, rather than just explaining it in the following paragraph, or else move the example up and preface it with "Here's an example of a form class", because it doesn't illustrate ->getForm().

Actually... Maybe it would be good to move it quite a bit up.... Up here:

+ * Forms are defined as classes that implement the Drupal\Core\Form\FormInterface
+ * and are built using the Drupal\Core\Form\FormBuilder class. Drupal provides a
+ * couple of utility classes which can be extended as a starting point for most
+ * basic forms the most commonly used of which is Drupal\Core\Form\FormBase.

How about leaving FormBuilder out of the text there, and just talking about form classes first, and then giving the form class example? Then you can start a new section and talk about the FormBuilder and ->getForm() stuff separately, instead of trying to merge them into one example and discussion? Most people don't really need to know about the FormBuilder class anyway -- they just need to know how to make a form class and how to call getForm() to display it, right? And many uses don't actually need to know about getForm(), because they'll be using a FormController class as the page controller...

f) By the way you can put section headers into API docs now, and make links to them, with @section, @subsection, and @ref:
https://drupal.org/node/1354#section
https://drupal.org/node/1354#ref
Could be useful?

g)

+ * Given the ExampleForm defined above \Drupal::formBuilder()->getForm('example_form')
+ * would return the rendered HTML of the form defined by ExampleForm::buildForm()
+ * or call the validateForm() and submitForm() methods depending on the current
+ * processing state.

A couple of commas would make this long sentence easier to parse? Or separate into several sentences?

h)

+ * Alternatively forms can be built directly via the routing system which will
+ * take care of calling \Drupal::formBuilder()->getForm().

You really don't like commas, do you? :) I would suggest one after Alternatively here.

This really would be a good place for a @section. How about one section about form classes, one about building forms, and one about form controllers?

i)

+ * Alternatively forms can be built directly via the routing system which will
+ * take care of calling \Drupal::formBuilder()->getForm().
+ *
+ * @code
+ * example.form:
+ * path: '/example-form'
+ * defaults:
+ *   _title: 'Example form'
+ *   _form: '\Drupal\example\Form\ExampleForm'
+ * @endcode
+ *

This doesn't explicitly say it's an example that should go into a routing.yml file, maybe it should? Also, I believe if you do this, you need to make ExampleForm extend a different class (a form controller class), not just BaseForm? Check on this...

Much better, thanks!

A few minor notes:

a) Normally, we don't want a blank line after a @section line.

+ * @section generating_forms Creating forms
  *

b) Normally, after a : we don't want a blank line.

+ * Here is an example of a Form class:
  *

c) Extra comma here after validateForm(), and I think it needs one after submiForm() instead:

+ * or call the validateForm(), and submitForm() methods depending on the current

d) Colon after "method" instead of ending in . -- or maybe say "For example:

+ * getForm() method will be passed along as additional arguments to the
+ * ExampleForm::buildForm() method.
+ *
  * @code

e) same as (d) -- colon:

+ * demonstrates the use of a routing.yml file to display a form at the the
+ * given route.
+ *
+ * @code

f) I think this needs some indentation:

+ * @code
+ * example.form:
+ * path: '/example-form'
+ * defaults:
+ *   _title: 'Example form'
+ *   _form: '\Drupal\mymodule\Form\ExampleForm'
+ * @endcode

(path and defaults should be indented two spaces, right?)

Other than those minor fixes, I think this looks very good!

Excellent work! Docs part is good too.

Thanks again! I found a couple of lines that were longer than 80 characters, and fixed the wrapping at commit time. Committed to 8.x.