? 776694-02.patch
Index: modules/field/field.api.php
===================================================================
RCS file: /cvs/drupal/drupal/modules/field/field.api.php,v
retrieving revision 1.71
diff -u -p -r1.71 field.api.php
--- modules/field/field.api.php	6 Apr 2010 16:49:12 -0000	1.71
+++ modules/field/field.api.php	21 Apr 2010 15:46:59 -0000
@@ -182,7 +182,7 @@ function hook_field_info() {
  * Perform alterations on Field API field types.
  *
  * @param $info
- *   Array of informations on widget types exposed by hook_field_info()
+ *   Array of information on widget types exposed by hook_field_info()
  *   implementations.
  */
 function hook_field_info_alter(&$info) {
@@ -607,7 +607,7 @@ function hook_field_widget_info() {
  * Perform alterations on Field API widget types.
  *
  * @param $info
- *   Array of informations on widget types exposed by hook_field_widget_info()
+ *   Array of information on widget types exposed by hook_field_widget_info()
  *   implementations.
  */
 function hook_field_widget_info_alter(&$info) {
@@ -655,7 +655,7 @@ function hook_field_widget_info_alter(&$
  * @param $items
  *   Array of default values for this field.
  * @param $delta
- *   The order of this item in the array of subelements (0, 1, 2, etc).
+ *   The order of this item in the array of sub-elements (0, 1, 2, etc).
  * @param $element
  *   A form element array containing basic properties for the widget:
  *   - #entity_type: The name of the entity the field is attached to.
@@ -670,7 +670,7 @@ function hook_field_widget_info_alter(&$
  *   - #required: A Boolean indicating whether the element value is required;
  *     for required multiple value fields, only the first widget's values are
  *     required.
- *   - #delta: The order of this item in the array of subelements; see $delta
+ *   - #delta: The order of this item in the array of sub-elements; see $delta
  *     above.
  * @return
  *   The form elements for a single widget for this field.
@@ -769,7 +769,7 @@ function hook_field_formatter_info() {
  * Perform alterations on Field API formatter types.
  *
  * @param $info
- *   Array of informations on formatter types exposed by
+ *   Array of information on formatter types exposed by
  *   hook_field_field_formatter_info() implementations.
  */
 function hook_field_formatter_info_alter(&$info) {
@@ -900,7 +900,10 @@ function hook_field_formatter_view($enti
  */
 
 /**
- * Act on field_attach_form.
+ * Acts when adding form elements to a form structure, for all fields
+ * for an entity.
+ *
+ * Add form elements for all fields for an entity to a form structure.
  *
  * This hook is invoked after the field module has performed the operation.
  *
@@ -945,7 +948,7 @@ function hook_field_attach_form($entity_
 }
 
 /**
- * Act on field_attach_load.
+ * Acts when loading fields for the current revisions of a group of entities.
  *
  * This hook is invoked after the field module has performed the operation.
  *
@@ -963,7 +966,7 @@ function hook_field_attach_load($entity_
 }
 
 /**
- * Act on field_attach_validate.
+ * Acts when field validation is performed against the field data in an entity.
  *
  * This hook is invoked after the field module has performed the operation.
  *
@@ -973,7 +976,7 @@ function hook_field_attach_validate($ent
 }
 
 /**
- * Act on field_attach_submit.
+ * Acts when a field is submitted by a form.
  *
  * This hook is invoked after the field module has performed the operation.
  *
@@ -983,7 +986,7 @@ function hook_field_attach_submit($entit
 }
 
 /**
- * Act on field_attach_presave.
+ * Acts just before field data is saved.
  *
  * This hook is invoked after the field module has performed the operation.
  *
@@ -993,7 +996,7 @@ function hook_field_attach_presave($enti
 }
 
 /**
- * Act on field_attach_insert.
+ * Acts when field data is saved for a new entity.
  *
  * This hook is invoked after the field module has performed the operation.
  *
@@ -1003,7 +1006,7 @@ function hook_field_attach_insert($entit
 }
 
 /**
- * Act on field_attach_update.
+ * Acts when field data is saved for an existing entity.
  *
  * This hook is invoked after the field module has performed the operation.
  *
@@ -1013,7 +1016,8 @@ function hook_field_attach_update($entit
 }
 
 /**
- * Act on field_attach_preprocess.
+ * Acts when populating the template variables with the field values
+ * available for rendering.
  *
  * This hook is invoked while preprocessing the field.tpl.php template file.
  *
@@ -1030,7 +1034,7 @@ function hook_field_attach_preprocess_al
 }
 
 /**
- * Act on field_attach_delete.
+ * Acts when deleting (all) field data for an existing entity.
  *
  * This hook is invoked after the field module has performed the operation.
  *
@@ -1040,7 +1044,7 @@ function hook_field_attach_delete($entit
 }
 
 /**
- * Act on field_attach_delete_revision.
+ * Acts when deleting field data for a single revision of an existing entity.
  *
  * This hook is invoked after the field module has performed the operation.
  *
@@ -1050,7 +1054,36 @@ function hook_field_attach_delete_revisi
 }
 
 /**
- * Act on field_attach_view.
+ * Acts when purging the field data for a single field on a single
+ * pseudo-entity.
+ *
+ * This hook is invoked in field_purge_data() and allows modules to act on
+ * purging data from a single field pseudo-entity.  For example, if a module
+ * relates data in the field with its own data, it may purge its own data
+ * during this process as well.
+ *
+ * @param $entity_type
+ *   The type of $entity; e.g. 'node' or 'user'.
+ * @param $entity
+ *   The pseudo-entity whose field data is being purged.
+ * @param $field
+ *   The (possibly deleted) field whose data is being purged.
+ * @param $instance
+ *   The deleted field instance whose data is being purged.
+ *
+ * See also @link field_purge Field API bulk data deletion @endlink
+ * @see field_purge_data()
+ */
+function hook_field_attach_purge($entity_type, $entity, $field, $instance) {
+  // find the corresponding data in mymodule and purge it
+  if ($entity_type == 'node') {
+    mymodule_remove_mydata($entity->nid);
+  }
+}
+
+/**
+ * Acts when preparing a renderable array for the field values of an
+ * entity.
  *
  * This hook is invoked after the field module has performed the operation.
  *
@@ -1066,9 +1099,9 @@ function hook_field_attach_view_alter(&$
 }
 
 /**
- * Act on field_language().
+ * Acts when the display language for a given entity is changed.
  *
- * This hook is invoked to alter the array of display languages for the given
+ * This hook is invoked to alter the display language for the given
  * entity.
  *
  * @param $display_language
@@ -1083,10 +1116,10 @@ function hook_field_language_alter(&$dis
 }
 
 /**
- * Act on field_available_languages().
+ * Acts when the available display languages for an entity are changed.
  *
- * This hook is invoked to alter the array of available languages for the given
- * field.
+ * This hook is invoked to alter the array of available languages for
+ * the given field.
  *
  * @param &$languages
  *   A reference to an array of language codes to be made available.
@@ -1099,7 +1132,7 @@ function hook_field_available_languages_
 }
 
 /**
- * Act on field_attach_create_bundle.
+ * Acts when a bundle is created.
  *
  * This hook is invoked after the field module has performed the operation.
  *
@@ -1109,7 +1142,7 @@ function hook_field_attach_create_bundle
 }
 
 /**
- * Act on field_attach_rename_bundle.
+ * Acts when a bundle is renamed.
  *
  * This hook is invoked after the field module has performed the operation.
  *
@@ -1119,7 +1152,7 @@ function hook_field_attach_rename_bundle
 }
 
 /**
- * Act on field_attach_delete_bundle.
+ * Acts when a bundle is deleted.
  *
  * This hook is invoked after the field module has performed the operation.
  *
@@ -1176,7 +1209,7 @@ function hook_field_storage_info() {
  * Perform alterations on Field API storage types.
  *
  * @param $info
- *   Array of informations on storage types exposed by
+ *   Array of information on storage types exposed by
  *   hook_field_field_storage_info() implementations.
  */
 function hook_field_storage_info_alter(&$info) {
@@ -1316,7 +1349,7 @@ function hook_field_storage_query($field
 }
 
 /**
- * Act on creation of a new field.
+ * Acts when a field is created.
  *
  * @param $field
  *   The field structure being created.
@@ -1325,7 +1358,7 @@ function hook_field_storage_create_field
 }
 
 /**
- * Act on deletion of a field.
+ * Acts when a field is deleted.
  *
  * @param $field
  *   The field being deleted.
@@ -1334,7 +1367,7 @@ function hook_field_storage_delete_field
 }
 
 /**
- * Act on deletion of a field instance.
+ * Acts when a field instance is deleted.
  *
  * @param $instance
  *   The instance being deleted.
@@ -1343,7 +1376,7 @@ function hook_field_storage_delete_insta
 }
 
 /**
- * Act before the storage backends load field data.
+ * Acts just before the storage backends load field data.
  *
  * This hook allows modules to load data before the Field Storage API,
  * optionally preventing the field storage module from doing so.
@@ -1379,7 +1412,7 @@ function hook_field_storage_pre_load($en
 }
 
 /**
- * Act before the storage backends insert field data.
+ * Acts just before the storage backends insert field data.
  *
  * This hook allows modules to store data before the Field Storage API,
  * optionally preventing the field storage module from doing so.
@@ -1416,7 +1449,7 @@ function hook_field_storage_pre_insert($
 }
 
 /**
- * Act before the storage backends update field data.
+ * Acts before the storage backends update field data.
  *
  * This hook allows modules to store data before the Field Storage API,
  * optionally preventing the field storage module from doing so.
@@ -1468,7 +1501,7 @@ function hook_field_storage_pre_update($
 }
 
 /**
- * Act before the storage backend runs the query.
+ * Invoked before the storage backend runs the query.
  *
  * This hook should be implemented by modules that use
  * hook_field_storage_pre_load(), hook_field_storage_pre_insert() and
@@ -1508,7 +1541,7 @@ function hook_field_storage_pre_query($f
  */
 
 /**
- * Act on a field being created.
+ * Acts when a field is created.
  *
  * This hook is invoked after the field is created and so it cannot modify the
  * field itself.
@@ -1522,7 +1555,7 @@ function hook_field_create_field($field)
 }
 
 /**
- * Act on a field instance being created.
+ * Acts when a field instance is created.
  *
  * This hook is invoked after the instance record is saved and so it cannot
  * modify the instance itself.
@@ -1534,7 +1567,7 @@ function hook_field_create_instance($ins
 }
 
 /**
- * Forbid a field update from occurring.
+ * Acts to forbid a field update from occurring.
  *
  * Any module may forbid any update for any reason. For example, the
  * field's storage module might forbid an update if it would change
@@ -1569,7 +1602,7 @@ function hook_field_update_field_forbid(
 }
 
 /**
- * Act on a field being updated.
+ * Acts when a field is updated.
  *
  * This hook is invoked just after field is updated.
  *
@@ -1584,7 +1617,7 @@ function hook_field_update_field($field,
 }
 
 /**
- * Act on a field being deleted.
+ * Acts when a field is deleted.
  *
  * This hook is invoked just after field is deleted.
  *
@@ -1595,7 +1628,7 @@ function hook_field_delete_field($field)
 }
 
 /**
- * Act on a field instance being updated.
+ * Acts when a field instance is updated.
  *
  * This hook is invoked after the instance record is saved and so it cannot
  * modify the instance itself.
@@ -1609,7 +1642,7 @@ function hook_field_update_instance($ins
 }
 
 /**
- * Act on a field instance being deleted.
+ * Acts when a field instance being deleted.
  *
  * This hook is invoked just after the instance is deleted.
  *
@@ -1620,7 +1653,7 @@ function hook_field_delete_instance($ins
 }
 
 /**
- * Act on field records being read from the database.
+ * Acts when a field record is read from the database.
  *
  * @param $field
  *   The field record just read from the database.
@@ -1629,7 +1662,7 @@ function hook_field_read_field($field) {
 }
 
 /**
- * Act on a field record being read from the database.
+ * Acts when a single field instance record is read from the database.
  *
  * @param $instance
  *   The instance record just read from the database.
Index: modules/field/field.attach.inc
===================================================================
RCS file: /cvs/drupal/drupal/modules/field/field.attach.inc,v
retrieving revision 1.86
diff -u -p -r1.86 field.attach.inc
--- modules/field/field.attach.inc	4 Apr 2010 12:48:18 -0000	1.86
+++ modules/field/field.attach.inc	21 Apr 2010 15:46:59 -0000
@@ -685,7 +685,7 @@ function field_attach_load($entity_type,
     _field_invoke_multiple('load', $entity_type, $queried_entities, $age, $options);
 
     // Invoke hook_field_attach_load(): let other modules act on loading the
-    // entitiy.
+    // entity.
     module_invoke_all('field_attach_load', $entity_type, $queried_entities, $age, $options);
 
     // Build cache data.
@@ -1383,7 +1383,7 @@ function field_attach_rename_bundle($ent
 }
 
 /**
- * Notify field.module the a bundle was deleted.
+ * Notify field.module that a bundle was deleted.
  *
  * This deletes the data for the field instances as well as the field instances
  * themselves. This function actually just marks the data and field instances
Index: modules/field/field.crud.inc
===================================================================
RCS file: /cvs/drupal/drupal/modules/field/field.crud.inc,v
retrieving revision 1.55
diff -u -p -r1.55 field.crud.inc
--- modules/field/field.crud.inc	28 Mar 2010 11:54:06 -0000	1.55
+++ modules/field/field.crud.inc	21 Apr 2010 15:46:59 -0000
@@ -1038,7 +1038,7 @@ function field_purge_batch($batch_size) 
  * @param $entity_type
  *   The type of $entity; e.g. 'node' or 'user'.
  * @param $entity
- *   The pseudo-entity whose field data to delete.
+ *   The pseudo-entity whose field data is being purged.
  * @param $field
  *   The (possibly deleted) field whose data is being purged.
  * @param $instance