Index: modules/field/field.attach.inc
===================================================================
RCS file: /cvs/drupal/drupal/modules/field/field.attach.inc,v
retrieving revision 1.22
diff -u -p -r1.22 field.attach.inc
--- modules/field/field.attach.inc	7 Jun 2009 00:00:57 -0000	1.22
+++ modules/field/field.attach.inc	17 Jun 2009 19:13:17 -0000
@@ -64,14 +64,14 @@ class FieldQueryException extends FieldE
  */
 
 /**
- * Argument for an insert operation.
+ * Argument for an update operation.
  * This is used in hook_field_storage_write when updating an
  * existing object.
  */
 define('FIELD_STORAGE_UPDATE', 'update');
 
 /**
- * Argument for an update operation.
+ * Argument for an insert operation.
  * This is used in hook_field_storage_write when inserting a new object.
  */
 define('FIELD_STORAGE_INSERT', 'insert');
@@ -86,7 +86,7 @@ define('FIELD_STORAGE_INSERT', 'insert')
  * Operate on Field API data attached to Drupal objects.
  *
  * Field Attach API functions load, store, generate Form API
- * structures, display, and perform a vareity of other functions for
+ * structures, display, and perform a variety of other functions for
  * field data connected to individual objects.
  *
  * Field Attach API functions generally take $obj_type and $object
@@ -360,12 +360,105 @@ function _field_invoke_multiple_default(
  *   The form structure to fill in.
  * @param $form_state
  *   An associative array containing the current state of the form.
- *
- * TODO : document the resulting $form structure, like we do for
- * field_attach_view().
+ * @return
+ *   An associative array that is combined the with original form. Note that the orginial $form
+ *   is also modified inside the call to field_attach_form. It is passed in by reference.
+     // The elements listed are the only ones either added of changed.
+ *   The $form array with a field named 'field_foo' will look like:
+ *   $form array(
+ *     '#fields' = > array(
+ *       // One sub-array where the key is the field name for each field in the bundle.
+ *       'field_foo' => array (
+ *         'field' => array(field array),
+ *         'instance' => array(field_instance array),
+ *         'form_path' => 'field_name',
+ *       )
+ *     //Unless it is Ahah then TRUE.
+ *     '#cache' => FALSE
+ *     // One sub-array where the key is the field name for each field in the bundle.
+ *     'field_foo' array(
+ *       #theme => 'field_multiple_value_form',
+ *       // Number of field values.
+ *       #multiple => 3,
+ *       //Field title.
+ *       #title => 'label',
+ *       // Whether or not it is required.
+ *       #required => FALSE,
+ *       //One numbered sub-array for each field value.
+ *       // Only multiple values and multiple form elements.
+ *       0 => array(
+ *         '#type' => 'widget type',
+ *         '#default_value' => 'value0',
+ *         // Whether or not field is required.
+ *         '#required' => TRUE,
+ *         '#columns' => array(
+ *           0 => 'value',
+ *           1 => 'format',
+ *         )
+ *         '#title' => 'label',
+ *         // Value index.
+ *         '#delta' => 0,
+ *         '#field_name' => 'field_name',
+ *         '#bundle' => $bundle,
+ *       )
+ *       // Only multiple values and multiple form elements.
+ *       1 => array(
+ *         '#type' => 'widget type',
+ *         '#default_value' => 'value1',
+ *         // Whether or not field is required.
+ *         '#required' => TRUE,
+ *         '#columns' => array(
+ *           0 => 'value',
+ *           1 => 'format',
+ *         )
+ *         '#title' => 'label',
+ *         // Value index.
+ *         '#delta' => 2,
+ *         '#field_name' => 'field_name',
+ *         '#bundle' => $bundle,
+ *       )
+ *       // Only multiple values and multiple form elements.
+ *       2 => array(
+ *         '#type' => 'widget type',
+ *         '#default_value' => 'value2',
+ *         '#columns' => array(
+ *           0 => 'value',
+ *           1 => 'format',
+ *       )
+ *       '#title' => 'label',
+ *       // Value index.
+ *       '#delta' => 2,
+ *       '#field_name' => 'field_name',
+ *       '#bundle' => $bundle,
+ *     )
+ *     '#field_name' => 'field_name',
+ *     '#tree' => TRUE,
+ *     '#weight' => 'weight',
+ *     // Only multiple values and single form element i.e. checkboxes.
+ *     '#type' => 'widget_type',
+ *     '#default_value' => array(
+ *       '#type' => 'widget_type',
+ *       '#default' =>  array(
+ *          0 => array(
+ *            'value' => 'value0',
+ *          1 => array(
+ *            'value' => 'value1',
+ *          2 => array(
+ *            'value' => 'value2',
+ *       // Whether or not field is required.
+ *       '#required' => FALSE
+ *       '#colums' => array(
+ *         0 => 'value',
+ *       '#title' => 'label',
+ *       '#delta' => 0,
+ *       '#field_name' => 'field_name'
+ *       '#bundle' => $bundle,
+ *       '#tree' => TRUE,
+ *       '#weight' => 'weight',
+ *     )
+ *   )
  */
 function field_attach_form($obj_type, $object, &$form, $form_state) {
-  // TODO : something's not right here : do we alter the form or return a value ?
   $form += (array) _field_invoke_default('form', $obj_type, $object, $form, $form_state);
 
   // Let other modules make changes to the form.
@@ -887,6 +980,58 @@ function field_attach_query_revisions($f
  *   Whether to display the teaser only, as on the main page.
  * @return
  *   A structured content array tree for drupal_render().
+ *   The 'view' operation constructs the $object in a way that you can use
+ *   drupal_render() to display the formatted output for an individual field.
+ *   i.e. print drupal_render($object->content['field_foo']);
+ *
+ *   The code supports both single value formatters, which theme an individual
+ *   item value, and multiple value formatters, which theme all values for the
+ *   field in a single theme. The multiple value formatters could be used, for
+ *   instance, to plot field values on a single map or display them in a graph.
+ *   Single value formatters are the default, multiple value formatters can be
+ *   designated as such in formatter_info().
+ *   The $object array will look like:
+ *     $object->content['field_foo']['wrapper'] = array(
+ *       '#theme' => 'field',
+ *       '#title' => 'label'
+ *       '#field_name' => 'field_name',
+ *       '#object' => $object,
+ *       '#object_type' => $obj_type,
+ *       // Value of the $teaser param of hook_node('view').
+ *       '#teaser' => $teaser,
+ *       'items' =>
+ *         0 => array(
+ *           '#item' => $items[0],
+ *           // Only for 'single-value' formatters
+ *           '#theme' => $theme,
+ *           '#field_name' => 'field_name',
+ *           '#bundle' => $bundle,
+ *           '#formatter' => $formatter_name,
+ *           '#settings' => $formatter_settings,
+ *           '#object' => $object,
+ *           '#object_type' => $obj_type,
+ *           '#delta' => 0,
+ *         ),
+ *         1 => array(
+ *           '#item' => $items[1],
+ *           // Only for 'single-value' formatters
+ *           '#theme' => $theme,
+ *           '#field_name' => 'field_name',
+ *           '#bundle' => $bundle_name,
+ *           '#formatter' => $formatter_name,
+ *           '#settings' => $formatter_settings,
+ *           '#object' => $object,
+ *           '#object_type' => $obj_type,
+ *           '#delta' => 1,
+ *         ),
+ *         // Only for 'multiple-value' formatters
+ *         '#theme' => $theme,
+ *         '#field_name' => 'field_name',
+ *         '#bundle' => $bundle_name,
+ *         '#formatter' => $formatter_name,
+ *         '#settings' => $formatter_settings,
+ *       ),
+ *     );
  */
 function field_attach_view($obj_type, $object, $teaser = FALSE) {
   // Let field modules sanitize their data for output.