Index: modules/system/system.api.php
===================================================================
RCS file: /cvs/drupal/drupal/modules/system/system.api.php,v
retrieving revision 1.102
diff -u -r1.102 system.api.php
--- modules/system/system.api.php	6 Nov 2009 03:59:06 -0000	1.102
+++ modules/system/system.api.php	6 Nov 2009 17:51:52 -0000
@@ -638,27 +638,29 @@
 }
 
 /**
- * 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 defined
- * in 'callback'. In case the code that calls drupal_get_form() also passes
- * parameters, then the 'callback' function will receive the
- * 'callback arguments' specified in hook_forms() before those that have been
- * passed to drupal_get_form().
- *
- * 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().
- *   These are always passed to the form builder and do not have to be specified
- *   manually in 'callback arguments'.
+ *   An array containing the original arguments provided to drupal_get_form()
+ *   or drupal_form_submit(). These are always passed to the form builder and
+ *   do not have to be specified manually in 'callback arguments'.
  *
  * @return
  *   An associative array whose keys define form_ids and whose values are an
Index: includes/form.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/form.inc,v
retrieving revision 1.393
diff -u -r1.393 form.inc
--- includes/form.inc	4 Nov 2009 05:39:14 -0000	1.393
+++ includes/form.inc	6 Nov 2009 17:51:52 -0000
@@ -440,14 +440,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__);