Documentation for hook_forms is incorrect

Note that the D6->D6 migration guide includes a bit of information about this change : http://drupal.org/node/144132#hook-forms

Moving to correct queue.

Note that hook_forms() is called from http://api.drupal.org/api/function/drupal_retrieve_form , which in turn is called from drupal_get_form() (with an intermediate function drupal_build_form() in Drupal 7).

In Drupal 5, the input args to drupal_retrieve_form() are $form_id and flexible additional arguments passed into drupal_get_form(). The arguments passed to hook_forms() are the form ID and the additional flexible arguments. Documentation of hook_forms() doesn't make this clear, in my opinion.

In Drupal 6, the input args to drupal_retrieve_form() are $form_id, $form_state, and the flexible arguments from drupal_get_form(). $form_state is removed from the arg list before calling drupal_retrieve_form() in Drupal 6 -- so hook_forms() works like Drupal 5 (form ID plus flexible arguments). Documentation of hook_forms() doesn't make this clear, in my opinion.

In Drupal 7, the input args to drupal_retrieve_form() are form ID and form state. What is passed to hook_forms() in D7 is $form_id, plus the 'args' component of $form_state, which actually comes from the flexible arguments of drupal_get_form(). This is almost correctly documented in the hook_forms() documentation, except that it doesn't make clear that $form_id is not in the $args array.

Also, the Drupal 7 documentation for drupal_retrieve_form() incorrectly implies that drupal_retrieve_form() takes the additional flexible arguments, but this is incorrect -- drupal_get_form() puts these into $form_state['args'] and the flexible arguments are not passed in that form to drupal_retrieve_form(). So the item for "additional ... arguments" should be removed from the Drupal 7 documentation of drupal_retrieve_form().

So, in my opinion, D7 needs a small patch for hook_forms() and one for drupal_retrieve_form(), and D6/D5 need completely different patches for hook_forms().

Here is a patch for Drupal 7 for review.

The last submitted patch failed testing.

This is a doc-only patch. Submitting for retest, as there is no way this patch caused tests to fail.

reuploading for bot

The lines are wrapped at considerably less than 80 characters. There is no reason to make them that short.

Here's a new patch, with some additional cleanup of wording, and wrapping at closer to 80 characters.

I'll review this after API freeze.

The last submitted patch failed testing.

Here's a new patch, which should apply.

jhodgdon requested that failed test be re-tested.

in the modules/system/system.api.php section, should "drupal-form_submit" be "drupal_form_submit"?

Yes, needs a new patch to fix that. thanks!

Here's a patch with that typo fixed.