Index: docs/developer/hooks/core.php
===================================================================
RCS file: /cvs/drupal-contrib/contributions/docs/developer/hooks/core.php,v
retrieving revision 1.169
diff -u -r1.169 core.php
--- docs/developer/hooks/core.php	17 Mar 2008 04:38:22 -0000	1.169
+++ docs/developer/hooks/core.php	20 Mar 2008 02:40:36 -0000
@@ -399,11 +399,36 @@
 }
 
 /**
- * Allows modules to declare their own form element types and specify their
+ * Allows modules to declare their own Forms API element types and specify their
  * default values.
  *
- * @return
- *  An array of element types
+ * This hook allows modules to declare their own form element types and to 
+ * specify their default values. The values returned by this hook will be 
+ * merged with the elements returned by hook_form() implementations and so
+ * can return defaults for any Form APIs keys in addition to those explicitly 
+ * mentioned below.
+ * 
+ * Each of the form element types defined by this hook is assumed to have
+ * a matching theme function, e.g. theme_elementtype(), which should be 
+ * registered with hook_theme() as normal.
+ *
+ * Form more information about custom element types see the explanation at 
+ * http://drupal.org/node/169815.
+ *
+ * @return
+ *  An associative array describing the element types being defined. The array
+ *  contains a sub-array for each element type, with the machine-readable type
+ *  name as the key. Each sub-array has a number of possible attributes:
+ *  - "#input": boolean indicating whether or not this element carries a value 
+ *    (even if it's hidden).
+ *  - "#process": array of callback functions taking $element and $form_state.
+ *  - "#after_build": array of callback functions taking $element and $form_state.
+ *  - "#validate": array of callback functions taking $form and $form_state.
+ *  - "#element_validate": array of callback functions taking $element and 
+ *    $form_state.
+ *  - "#pre_render": array of callback functions taking $element and $form_state.
+ *  - "#post_render": array of callback functions taking $element and $form_state.
+ *  - "#submit": array of callback functions taking $form and $form_state.
  */
 function hook_elements() {
   $type['filter_format'] = array('#input' => TRUE);