Index: modules/field/field.attach.inc
===================================================================
RCS file: /cvs/drupal/drupal/modules/field/field.attach.inc,v
retrieving revision 1.22
diff -u -p -s -r1.22 field.attach.inc
--- modules/field/field.attach.inc	7 Jun 2009 00:00:57 -0000	1.22
+++ modules/field/field.attach.inc	8 Jun 2009 20:35:48 -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
@@ -887,6 +887,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.