diff --git includes/form.inc includes/form.inc
index 21008c0..3dfb859 100644
--- includes/form.inc
+++ includes/form.inc
@@ -29,21 +29,85 @@
  * presentation, while simplifying code and reducing the amount of HTML that
  * must be explicitly generated by modules.
  *
- * The drupal_get_form() function handles retrieving and processing an HTML
- * form for modules automatically. For example:
+ * The drupal_get_form() function handles retrieving, processing, and
+ * displaying a rendered HTML form for modules automatically. drupal_get_form()
+ * takes as arguments $form, $form_state, and optional arguments passed to
+ * drupal_get_form(). For example:
  *
  * @code
- *   // Display the user registration form.
- *   $output = drupal_get_form('user_register_form');
+ * $form = drupal_get_form('some_example_form');
+ * ...
+ * function some_example_form($form, &$form_state) {
+ *   $form['submit'] = array('#type' => 'submit', '#value' => t('Submit'));
+ * }
+ * function some_example_form_validate($form, &$form_state) {
+ *   // Validation logic
+ * }
+ * function some_example_form_submit($form, &$form_state) {
+ *   // submission logic
+ * }
+ * @endcode
+ *
+ * Or with any number of additional arguments:
+ *
+ * @code
+ * $extra_build_information = "extra build information";
+ * $form = drupal_get_form('some_example_form', $extra_build_information);
+ * ...
+ * function some_example_form($form, &$form_state, $extra) {
+ *   $form['submit'] = array('#type' => 'submit', '#value' => $extra);
+ * }
  * @endcode
  *
+ * In the form builder, validation, submission, and #ajax['callback'] functions,
+ * $form_state has enormous influence on the processing of the form.
+ * Its keys are:
+ *
+ * - 'values': An associative array of values which were submitted to the form.
+ *   The validation functions and submit functions use this array for nearly all
+ *   their decisionmaking. (Note that
+ *   @link http://api.drupal.org/api/drupal/developer--topics--forms_api_reference.html/7#tree #tree @endlink
+ *   determines whether the values are
+ *   a flat array or an array whose structure parallels the $form array.)
+ * - 'rebuild': If the submit function sets $form_state['rebuild'] to TRUE,
+ *   submission is not completed and instead the form is rebuilt using any
+ *   information that the submit function has made available to the form builder
+ *   function via $form_state. This is commonly used for wizard-style
+ *   multistep forms, add-more buttons, and the like.
+ * - 'redirect': a URL which will be used to redirect the form on submission.
+ *   See drupal_redirect_form() for complete information.
+ * - 'storage': $form_state['storage'] is not a special key, and no specific
+ *   support is provided for it in the Form API, but by convention it is
+ *   the location where application-specific data is stored for communication
+ *   between the submit, validation, and form builder functions, especially
+ *   in a multistep-style form.
+ * - 'triggering_element': (read-only) The form element that triggered
+ *   submission. This is the same as the deprecated
+ *   $form_state['clicked_button']. It is the element which caused submission,
+ *   which may or may not be a button (in the case of AJAX forms.)
+ * - 'cache': (internal) used typically with #ajax. $form_state['cache'] = TRUE
+ *   forces FAPI to turn on persistent storage for the $form.
+ * - 'input': (internal) This is the array of values in the $POST. For security
+ *   reasons, it must not be referred to.
+ *
+ * Note that all $form_state keys not listed in form_state_keys_no_cache() are
+ * persisted, so are available in the validation, submission, and the form
+ * builder function (after first submission). In addition, they're available
+ * to a #ajax['callback'] function, if any. By convention, user values that
+ * are intended to be persisted are stored in $form_state['storage'] though.
+ *
  * Forms can also be built and submitted programmatically without any user input
- * using the drupal_form_submit() function.
+ * using the drupal_execute() function.
  *
  * For information on the format of the structured arrays used to define forms,
  * and more detailed explanations of the Form API workflow, see the
  * @link http://api.drupal.org/api/file/developer/topics/forms_api_reference.html reference @endlink
- * and the @link http://api.drupal.org/api/file/developer/topics/forms_api.html quickstart guide. @endlink
+ * and the
+ * @link http://drupal.org/node/37775 Form API section of the handbook. @endlink
+ *
+ * In addition, there is a set of Form API tutorials in
+ * @link form_example_tutorial.inc the Form Example Tutorial @endlink which
+ * provide basics all the way up to multistep forms.
  */
 
 /**