Index: modules/system/system.api.php
===================================================================
RCS file: /cvs/drupal/drupal/modules/system/system.api.php,v
retrieving revision 1.48
diff -u -r1.48 system.api.php
--- modules/system/system.api.php	11 Jul 2009 13:56:22 -0000	1.48
+++ modules/system/system.api.php	13 Jul 2009 20:53:16 -0000
@@ -399,25 +399,35 @@
 }
 
 /**
- * Map form_ids to builder functions.
+ * Map form_ids to form builder functions.
  *
- * This hook allows modules to build multiple forms from a single form "factory"
- * function but each form will have a different form id for submission,
- * validation, theming or alteration by other modules.
- *
- * The callback arguments will be passed as parameters to the function. Callers
- * of drupal_get_form() are also able to pass in parameters. These will be
- * appended after those specified by hook_forms().
- *
- * See node_forms() for an actual example of how multiple forms share a common
- * building function.
+ * By default, when drupal_get_form() is called, the system will look
+ * for a function with the same name as the form ID, and use that function
+ * to build the form. This hook allows you to override that behavior in two
+ * ways. 
+ * 
+ * First, you can use this hook to tell the form system to use a
+ * different function to build certain forms in your module; this is
+ * often used to define a form "factory" function that is used to
+ * build several similar forms. In this case, your hook implementation
+ * will likely ignore all of the input arguments. See node_forms() for
+ * an example of this.
+ *
+ * Second, you could use this hook to define how to build a form with
+ * a dynamically-generated form ID. In this case, you would need to
+ * verify that the $form_id input matched your module's format for
+ * dynamically-generated form IDs, and if so, act appropriately.
  *
  * @param $form_id
  *   The unique string identifying the desired form.
  * @param $args
- *   An array containing the original arguments provided to drupal_get_form().
+ *   An array containing the additional arguments provided to
+ *   drupal_get_form() or drupal_form_submit().
  * @return
- *   An array keyed by form_id with callbacks and optional, callback arguments.
+ *   An associative array, whose keys are form IDs. The array values
+ *   are associative arrays, with element 'callback' giving the callback
+ *   function that generates the form, and optionally 'callback arguments', 
+ *   giving function arguments to pass to that function.
  */
 function hook_forms($form_id, $args) {
   $forms['mymodule_first_form'] = array(
Index: includes/form.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/form.inc,v
retrieving revision 1.349
diff -u -r1.349 form.inc
--- includes/form.inc	7 Jul 2009 22:32:17 -0000	1.349
+++ includes/form.inc	13 Jul 2009 20:53:16 -0000
@@ -399,14 +399,9 @@
  *   using different $form_ids can implement hook_forms(), which maps
  *   different $form_id values to the proper form constructor function.
  * @param $form_state
- *   A keyed array containing the current state of the form.
- * @param ...
- *   Any additional arguments needed by the unique form constructor
- *   function. Generally, these are any arguments passed into the
- *   drupal_get_form() or drupal_form_submit() functions after the first
- *   argument. If a module implements hook_forms(), it can examine
- *   these additional arguments and conditionally return different
- *   builder functions as well.
+ *   A keyed array containing the current state of the form, including
+ *   the additional arguments to drupal_get_form() or drupal_form_submit()
+ *   in the 'args' component of the array.
  */
 function drupal_retrieve_form($form_id, &$form_state) {
   $forms = &drupal_static(__FUNCTION__);