#675116 by jhodgdon, sun: Fixed Several problems in field.api.php and field_ui().api.php.

2 files changed, 270 insertions, 186 deletions

diff --git a/modules/field/field.api.php b/modules/field/field.api.php
index 24b1bb169..cb7666f71 100644
--- a/modules/field/field.api.php
+++ b/modules/field/field.api.php
@@ -10,8 +10,8 @@
  * Expose "pseudo-field" components on fieldable entities.
  *
  * Field UI's 'Manage fields' page lets users re-order fields, but also
- * non-field components. For nodes, that would be title, menu settings, or
- * other elements exposed by contributed modules through hook_form() or
+ * non-field components. For nodes, these include the title, menu settings, and
+ * other elements exposed by contributed modules through hook_form() and
  * hook_form_alter().
  *
  * Fieldable entities or contributed modules that want to have their components
@@ -93,6 +93,7 @@ function hook_field_extra_fields_alter(&$info) {
  * can be attached to a fieldable entity. hook_field_info() defines the basic
  * properties of a field type, and a variety of other field hooks are called by
  * the Field Attach API to perform field-type-specific actions.
+ *
  * @see hook_field_info()
  * @see hook_field_info_alter()
  * @see hook_field_schema()
@@ -109,8 +110,9 @@ function hook_field_extra_fields_alter(&$info) {
  * The Field Types API also defines two kinds of pluggable handlers: widgets
  * and formatters, which specify how the field appears in edit forms and in
  * displayed entities. Widgets and formatters can be implemented by a field-type
- * module for it's own field types, or by a third-party module to extend the
+ * module for its own field types, or by a third-party module to extend the
  * behavior of existing field types.
+ *
  * @see hook_field_widget_info()
  * @see hook_field_formatter_info()
  *
@@ -131,13 +133,12 @@ function hook_field_extra_fields_alter(&$info) {
  *     settings.
  *   - instance_settings: An array whose keys are the names of the settings
  *     available for instances of the field type, and whose values are the
- *     default values for those settings.
- *     Instance-level settings can have different values on each field
- *     instance, and thus allow greater flexibility than field-level settings.
- *     It is recommended to put settings at the instance level whenever
- *     possible. Notable exceptions: settings acting on the schema definition,
- *     or settings that Views needs to use across field instances (e.g. list of
- *     allowed values).
+ *     default values for those settings. Instance-level settings can have
+ *     different values on each field instance, and thus allow greater
+ *     flexibility than field-level settings. It is recommended to put settings
+ *     at the instance level whenever possible. Notable exceptions: settings
+ *     acting on the schema definition, or settings that Views needs to use
+ *     across field instances (for example, the list of allowed values).
  *   - default_widget: The machine name of the default widget to be used by
  *     instances of this field type, when no widget is specified in the
  *     instance definition. This widget must be available whenever the field
@@ -148,6 +149,8 @@ function hook_field_extra_fields_alter(&$info) {
  *     instance definition. This formatter must be available whenever the field
  *     type is available (i.e. provided by the field type module, or by a module
  *     the field type module depends on).
+ *
+ * @see hook_field_info_alter()
  */
 function hook_field_info() {
   return array(
@@ -182,7 +185,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 field types exposed by hook_field_info()
  *   implementations.
  */
 function hook_field_info_alter(&$info) {
@@ -204,23 +207,22 @@ function hook_field_info_alter(&$info) {
  *
  * @param $field
  *   A field structure.
+ *
  * @return
  *   An associative array with the following keys:
- *   - columns: An array of Schema API column specifications, keyed by column name.
- *     This specifies what comprises a value for a given field.
- *     For example, a value for a number field is simply 'value', while a
- *     value for a formatted text field is the combination of 'value' and
- *     'format'.
- *     It is recommended to avoid having the columns definitions depend on
- *     field settings when possible.
- *     No assumptions should be made on how storage engines internally use the
- *     original column name to structure their storage.
+ *   - columns: An array of Schema API column specifications, keyed by column
+ *     name. This specifies what comprises a value for a given field. For
+ *     example, a value for a number field is simply 'value', while a value for
+ *     a formatted text field is the combination of 'value' and 'format'. It is
+ *     recommended to avoid having the column definitions depend on field
+ *     settings when possible. No assumptions should be made on how storage
+ *     engines internally use the original column name to structure their
+ *     storage.
  *   - indexes: An array of Schema API indexes definitions. Only columns that
- *     appear in the 'columns' array are allowed.
- *     Those indexes will be used as default indexes. Callers of
- *     field_create_field() can specify additional indexes, or, at their own
- *     risk, modify the default indexes specified by the field-type module.
- *     Some storage engines might not support indexes.
+ *     appear in the 'columns' array are allowed. Those indexes will be used as
+ *     default indexes. Callers of field_create_field() can specify additional
+ *     indexes, or, at their own risk, modify the default indexes specified by
+ *     the field-type module. Some storage engines might not support indexes.
  */
 function hook_field_schema($field) {
   if ($field['type'] == 'text_long') {
@@ -257,10 +259,10 @@ function hook_field_schema($field) {
 }
 
 /**
- * Defines custom load behavior for this module's field types.
+ * Define custom load behavior for this module's field types.
  *
  * Unlike most other field hooks, this hook operates on multiple entities. The
- * $entities, $instances and $items parameters are arrays keyed by entity id.
+ * $entities, $instances and $items parameters are arrays keyed by entity ID.
  * For performance reasons, information for all available entity should be
  * loaded in a single query where possible.
  *
@@ -270,25 +272,26 @@ function hook_field_schema($field) {
  * hook_field_load() is run on those as well. Use
  * hook_field_formatter_prepare_view() instead.
  *
+ * Make changes or additions to field values by altering the $items parameter by
+ * reference. There is no return value.
+ *
  * @param $entity_type
  *   The type of $entity.
  * @param $entities
- *   Array of entities being loaded, keyed by entity id.
+ *   Array of entities being loaded, keyed by entity ID.
  * @param $field
  *   The field structure for the operation.
  * @param $instances
  *   Array of instance structures for $field for each entity, keyed by entity
- *   id.
+ *   ID.
  * @param $langcode
- *   The language associated to $items.
+ *   The language code associated with $items.
  * @param $items
- *   Array of field values already loaded for the entities, keyed by entity id.
+ *   Array of field values already loaded for the entities, keyed by entity ID.
+ *   Store your changes in this parameter (passed by reference).
  * @param $age
  *   FIELD_LOAD_CURRENT to load the most recent revision for all fields, or
  *   FIELD_LOAD_REVISION to load the version indicated by each entity.
- * @return
- *   Changes or additions to field values are done by altering the $items
- *   parameter by reference.
  */
 function hook_field_load($entity_type, $entities, $field, $instances, $langcode, &$items, $age) {
   // Sample code from text.module: precompute sanitized strings so they are
@@ -308,27 +311,29 @@ function hook_field_load($entity_type, $entities, $field, $instances, $langcode,
 }
 
 /**
- * Prepares field values prior to display.
+ * Prepare field values prior to display.
  *
  * This hook is invoked before the field values are handed to formatters
  * for display, and runs before the formatters' own
  * hook_field_formatter_prepare_view().
- * @see hook_field_formatter_prepare_view()
  *
  * Unlike most other field hooks, this hook operates on multiple entities. The
- * $entities, $instances and $items parameters are arrays keyed by entity id.
+ * $entities, $instances and $items parameters are arrays keyed by entity ID.
  * For performance reasons, information for all available entities should be
  * loaded in a single query where possible.
  *
+ * Make changes or additions to field values by altering the $items parameter by
+ * reference. There is no return value.
+ *
  * @param $entity_type
  *   The type of $entity.
  * @param $entities
- *   Array of entities being displayed, keyed by entity id.
+ *   Array of entities being displayed, keyed by entity ID.
  * @param $field
  *   The field structure for the operation.
  * @param $instances
  *   Array of instance structures for $field for each entity, keyed by entity
- *   id.
+ *   ID.
  * @param $langcode
  *   The language associated to $items.
  * @param $items
@@ -336,7 +341,7 @@ function hook_field_load($entity_type, $entities, $field, $instances, $langcode,
  */
 function hook_field_prepare_view($entity_type, $entities, $field, $instances, $langcode, &$items) {
   // Sample code from image.module: if there are no images specified at all,
-  // use the default.
+  // use the default image.
   foreach ($entities as $id => $entity) {
     if (empty($items[$id]) && $field['settings']['default_image']) {
       if ($file = file_load($field['settings']['default_image'])) {
@@ -351,7 +356,10 @@ function hook_field_prepare_view($entity_type, $entities, $field, $instances, $l
 }
 
 /**
- * Define custom validate behavior for this module's field types.
+ * Validate this module's field data.
+ *
+ * If there are validation problems, add to the $errors array (passed by
+ * reference). There is no return value.
  *
  * @param $entity_type
  *   The type of $entity.
@@ -362,7 +370,7 @@ function hook_field_prepare_view($entity_type, $entities, $field, $instances, $l
  * @param $instance
  *   The instance structure for $field on $entity's bundle.
  * @param $langcode
- *   The language associated to $items.
+ *   The language associated with $items.
  * @param $items
  *   $entity->{$field['field_name']}[$langcode], or an empty array if unset.
  * @param $errors
@@ -370,8 +378,9 @@ function hook_field_prepare_view($entity_type, $entities, $field, $instances, $l
  *   already been reported for the entity. The function should add its errors
  *   to this array. Each error is an associative array, with the following
  *   keys and values:
- *   - 'error': an error code (should be a string, prefixed with the module name)
- *   - 'message': the human readable message to be displayed.
+ *   - error: An error code (should be a string, prefixed with the module
+ *     name).
+ *   - message: The human readable message to be displayed.
  */
 function hook_field_validate($entity_type, $entity, $field, $instance, $langcode, &$items, &$errors) {
   foreach ($items as $delta => $item) {
@@ -389,6 +398,9 @@ function hook_field_validate($entity_type, $entity, $field, $instance, $langcode
 /**
  * Define custom presave behavior for this module's field types.
  *
+ * Make changes or additions to field values by altering the $items parameter by
+ * reference. There is no return value.
+ *
  * @param $entity_type
  *   The type of $entity.
  * @param $entity
@@ -398,7 +410,7 @@ function hook_field_validate($entity_type, $entity, $field, $instance, $langcode
  * @param $instance
  *   The instance structure for $field on $entity's bundle.
  * @param $langcode
- *   The language associated to $items.
+ *   The language associated with $items.
  * @param $items
  *   $entity->{$field['field_name']}[$langcode], or an empty array if unset.
  */
@@ -417,6 +429,8 @@ function hook_field_presave($entity_type, $entity, $field, $instance, $langcode,
 /**
  * Define custom insert behavior for this module's field types.
  *
+ * Invoked from field_attach_insert().
+ *
  * @param $entity_type
  *   The type of $entity.
  * @param $entity
@@ -426,16 +440,19 @@ function hook_field_presave($entity_type, $entity, $field, $instance, $langcode,
  * @param $instance
  *   The instance structure for $field on $entity's bundle.
  * @param $langcode
- *   The language associated to $items.
+ *   The language associated with $items.
  * @param $items
  *   $entity->{$field['field_name']}[$langcode], or an empty array if unset.
  */
 function hook_field_insert($entity_type, $entity, $field, $instance, $langcode, &$items) {
+  // @todo Needs function body.
 }
 
 /**
  * Define custom update behavior for this module's field types.
  *
+ * Invoked from field_attach_update().
+ *
  * @param $entity_type
  *   The type of $entity.
  * @param $entity
@@ -445,11 +462,12 @@ function hook_field_insert($entity_type, $entity, $field, $instance, $langcode,
  * @param $instance
  *   The instance structure for $field on $entity's bundle.
  * @param $langcode
- *   The language associated to $items.
+ *   The language associated with $items.
  * @param $items
  *   $entity->{$field['field_name']}[$langcode], or an empty array if unset.
  */
 function hook_field_update($entity_type, $entity, $field, $instance, $langcode, &$items) {
+  // @todo Needs function body.
 }
 
 /**
@@ -491,7 +509,8 @@ function hook_field_storage_update_field($field, $prior_field, $has_data) {
 /**
  * Define custom delete behavior for this module's field types.
  *
- * This hook is invoked just before the data is deleted from field storage.
+ * This hook is invoked just before the data is deleted from field storage
+ * in field_attach_delete().
  *
  * @param $entity_type
  *   The type of $entity.
@@ -502,18 +521,20 @@ function hook_field_storage_update_field($field, $prior_field, $has_data) {
  * @param $instance
  *   The instance structure for $field on $entity's bundle.
  * @param $langcode
- *   The language associated to $items.
+ *   The language associated with $items.
  * @param $items
  *   $entity->{$field['field_name']}[$langcode], or an empty array if unset.
  */
 function hook_field_delete($entity_type, $entity, $field, $instance, $langcode, &$items) {
+  // @todo Needs function body.
 }
 
 /**
- * Define custom delete_revision behavior for this module's field types.
+ * Define custom revision delete behavior for this module's field types.
  *
- * This hook is invoked just before the data is deleted from field storage,
- * and will only be called for fieldable types that are versioned.
+ * This hook is invoked just before the data is deleted from field storage
+ * in field_attach_delete_revision(), and will only be called for fieldable
+ * types that are versioned.
  *
  * @param $entity_type
  *   The type of $entity.
@@ -524,11 +545,12 @@ function hook_field_delete($entity_type, $entity, $field, $instance, $langcode,
  * @param $instance
  *   The instance structure for $field on $entity's bundle.
  * @param $langcode
- *   The language associated to $items.
+ *   The language associated with $items.
  * @param $items
  *   $entity->{$field['field_name']}[$langcode], or an empty array if unset.
  */
 function hook_field_delete_revision($entity_type, $entity, $field, $instance, $langcode, &$items) {
+  // @todo Needs function body.
 }
 
 /**
@@ -559,6 +581,7 @@ function hook_field_prepare_translation($entity_type, $entity, $field, $instance
  *   An item that may or may not be empty.
  * @param $field
  *   The field to which $item belongs.
+ *
  * @return
  *   TRUE if $field's type considers $item not to contain any data;
  *   FALSE otherwise.
@@ -576,16 +599,15 @@ function hook_field_is_empty($item, $field) {
  * Widgets are Form API elements with additional processing capabilities.
  * Widget hooks are typically called by the Field Attach API during the
  * creation of the field form structure with field_attach_form().
+ *
  * @see hook_field_widget_info_alter()
  * @see hook_field_widget_form()
  * @see hook_field_widget_error()
  *
  * @return
  *   An array describing the widget types implemented by the module.
- *
  *   The keys are widget type names. To avoid name clashes, widget type
  *   names should be prefixed with the name of the module that exposes them.
- *
  *   The values are arrays describing the widget type, with the following
  *   key/value pairs:
  *   - label: The human-readable name of the widget type.
@@ -594,17 +616,19 @@ function hook_field_is_empty($item, $field) {
  *   - settings: An array whose keys are the names of the settings available
  *     for the widget type, and whose values are the default values for those
  *     settings.
- *   - behaviors: (optional) An array describing behaviors of the widget.
- *     - multiple values:
- *       FIELD_BEHAVIOR_DEFAULT (default) if the widget allows the input of one
- *       single field value (most common case). The widget will be repeated for
- *       each value input.
- *       FIELD_BEHAVIOR_CUSTOM if one single copy of the widget can receive
- *       several field values. Examples: checkboxes, multiple select,
- *       comma-separated textfield...
- *     - default value:
- *       FIELD_BEHAVIOR_DEFAULT (default) if the widget accepts default values.
- *       FIELD_BEHAVIOR_NONE if the widget does not support default values.
+ *   - behaviors: (optional) An array describing behaviors of the widget, with
+ *     the following elements:
+ *     - multiple values: One of the following constants:
+ *       - FIELD_BEHAVIOR_DEFAULT: (default) If the widget allows the input of
+ *         one single field value (most common case). The widget will be
+ *         repeated for each value input.
+ *       - FIELD_BEHAVIOR_CUSTOM: If one single copy of the widget can receive
+ *         several field values. Examples: checkboxes, multiple select,
+ *         comma-separated textfield.
+ *     - default value: One of the following constants:
+ *       - FIELD_BEHAVIOR_DEFAULT: (default) If the widget accepts default
+ *         values.
+ *       - FIELD_BEHAVIOR_NONE: if the widget does not support default values.
  */
 function hook_field_widget_info() {
     return array(
@@ -638,7 +662,6 @@ function hook_field_widget_info() {
   );
 }
 
-
 /**
  * Perform alterations on Field API widget types.
  *
@@ -657,7 +680,7 @@ function hook_field_widget_info_alter(&$info) {
 }
 
 /**
- * Return a single form element for a field widget.
+ * Return the form for a single field widget.
  *
  * Field widget form elements should be based on the passed in $element, which
  * contains the base form element properties derived from the field
@@ -665,11 +688,11 @@ function hook_field_widget_info_alter(&$info) {
  *
  * Field API will set the weight, field name and delta values for each form
  * element. If there are multiple values for this field, the Field API will
- * call this function as many times as needed.
+ * invoke this hook as many times as needed.
  *
  * Note that, depending on the context in which the widget is being included
  * (regular entity edit form, 'default value' input in the field settings form,
- * etc...), the passed in values for $field and $instance might be different
+ * etc.), the passed in values for $field and $instance might be different
  * from the official definitions returned by field_info_field() and
  * field_info_instance(). If the widget uses Form API callbacks (like
  * #element_validate, #value_callback...) that need to access the $field or
@@ -687,7 +710,7 @@ function hook_field_widget_info_alter(&$info) {
  * @param $instance
  *   The field instance.
  * @param $langcode
- *   The language associated to $items.
+ *   The language associated with $items.
  * @param $items
  *   Array of default values for this field.
  * @param $delta
@@ -708,6 +731,7 @@ function hook_field_widget_info_alter(&$info) {
  *     required.
  *   - #delta: The order of this item in the array of subelements; see $delta
  *     above.
+ *
  * @return
  *   The form elements for a single widget for this field.
  */
@@ -729,9 +753,9 @@ function hook_field_widget_form(&$form, &$form_state, $field, $instance, $langco
  * @param $error
  *   An associative array with the following key-value pairs, as returned by
  *   hook_field_validate():
- *   - 'error': the error code. Complex widgets might need to report different
+ *   - error: the error code. Complex widgets might need to report different
  *     errors to different form elements inside the widget.
- *   - 'message': the human readable message to be displayed.
+ *   - message: the human readable message to be displayed.
  * @param $form
  *   The form array.
  * @param $form_state
@@ -748,17 +772,10 @@ function hook_field_widget_error($element, $error, $form, &$form_state) {
  * called by the Field Attach API field_attach_prepare_view() and
  * field_attach_view() functions.
  *
- * @see hook_field_formatter_info()
- * @see hook_field_formatter_info_alter()
- * @see hook_field_formatter_view()
- * @see hook_field_formatter_prepare_view()
- *
  * @return
  *   An array describing the formatter types implemented by the module.
- *
  *   The keys are formatter type names. To avoid name clashes, formatter type
  *   names should be prefixed with the name of the module that exposes them.
- *
  *   The values are arrays describing the formatter type, with the following
  *   key/value pairs:
  *   - label: The human-readable name of the formatter type.
@@ -767,6 +784,10 @@ function hook_field_widget_error($element, $error, $form, &$form_state) {
  *   - settings: An array whose keys are the names of the settings available
  *     for the formatter type, and whose values are the default values for
  *     those settings.
+ *
+ * @see hook_field_formatter_info_alter()
+ * @see hook_field_formatter_view()
+ * @see hook_field_formatter_prepare_view()
  */
 function hook_field_formatter_info() {
   return array(
@@ -800,7 +821,6 @@ function hook_field_formatter_info() {
   );
 }
 
-
 /**
  * Perform alterations on Field API formatter types.
  *
@@ -826,39 +846,39 @@ function hook_field_formatter_info_alter(&$info) {
  * which displays properties of the referenced entities such as name or type.
  *
  * This hook is called after the field type's own hook_field_prepare_view().
- * @see hook_field_prepare_view()
  *
  * Unlike most other field hooks, this hook operates on multiple entities. The
- * $entities, $instances and $items parameters are arrays keyed by entity id.
+ * $entities, $instances and $items parameters are arrays keyed by entity ID.
  * For performance reasons, information for all available entities should be
  * loaded in a single query where possible.
  *
  * @param $entity_type
  *   The type of $entity.
  * @param $entities
- *   Array of entities being displayed, keyed by entity id.
+ *   Array of entities being displayed, keyed by entity ID.
  * @param $field
  *   The field structure for the operation.
  * @param $instances
  *   Array of instance structures for $field for each entity, keyed by entity
- *   id.
+ *   ID.
  * @param $langcode
  *   The language the field values are to be shown in. If no language is
  *   provided the current language is used.
  * @param $items
- *   Array of field values for the entities, keyed by entity id.
+ *   Array of field values for the entities, keyed by entity ID.
  * @param $displays
- *   Array of display settings to use for each entity, keyed by entity id.
+ *   Array of display settings to use for each entity, keyed by entity ID.
+ *
  * @return
  *   Changes or additions to field values are done by altering the $items
  *   parameter by reference.
  */
 function hook_field_formatter_prepare_view($entity_type, $entities, $field, $instances, $langcode, &$items, $displays) {
-
+  // @todo Needs function body.
 }
 
 /**
- * Builds a renderable array for a field value.
+ * Build a renderable array for a field value.
  *
  * @param $entity_type
  *   The type of $entity.
@@ -869,7 +889,7 @@ function hook_field_formatter_prepare_view($entity_type, $entities, $field, $ins
  * @param $instance
  *   The field instance.
  * @param $langcode
- *   The language associated to $items.
+ *   The language associated with $items.
  * @param $items
  *   Array of values for this field.
  * @param $display
@@ -939,8 +959,20 @@ function hook_field_formatter_view($entity_type, $entity, $field, $instance, $la
  * Act on field_attach_form.
  *
  * This hook is invoked after the field module has performed the operation.
+ * Implementing modules should alter the $form or $form_state parameters.
  *
- * See field_attach_form() for details and arguments.
+ * @param $entity_type
+ *   The type of $entity; for example, 'node' or 'user'.
+ * @param $entity
+ *   The entity for which to load form elements, used to initialize
+ *   default form values.
+ * @param $form
+ *   The form structure to fill in.
+ * @param $form_state
+ *   An associative array containing the current state of the form.
+ * @param $langcode
+ *   The language the field values are going to be entered in. If no language
+ *   is provided the default site language will be used.
  */
 function hook_field_attach_form($entity_type, $entity, &$form, &$form_state, $langcode) {
   $tids = array();
@@ -981,13 +1013,13 @@ function hook_field_attach_form($entity_type, $entity, &$form, &$form_state, $la
 }
 
 /**
- * Act on field_attach_load.
+ * Act on field_attach_load().
  *
  * This hook is invoked after the field module has performed the operation.
  *
  * Unlike other field_attach hooks, this hook accounts for 'multiple loads'.
  * Instead of the usual $entity parameter, it accepts an array of entities,
- * indexed by entity id. For performance reasons, information for all available
+ * indexed by entity ID. For performance reasons, information for all available
  * entities should be loaded in a single query where possible.
  *
  * The changes made to the entities' field values get cached by the field cache
@@ -995,106 +1027,116 @@ function hook_field_attach_form($entity_type, $entity, &$form, &$form_state, $la
  *
  * See field_attach_load() for details and arguments.
  */
-function hook_field_attach_load($entity_type, $entities, $age) {
+function hook_field_attach_load($entity_type, &$entities, $age, $options) {
+  // @todo Needs function body.
 }
 
 /**
- * Act on field_attach_validate.
+ * Act on field_attach_validate().
  *
  * This hook is invoked after the field module has performed the operation.
  *
  * See field_attach_validate() for details and arguments.
  */
 function hook_field_attach_validate($entity_type, $entity, &$errors) {
+  // @todo Needs function body.
 }
 
 /**
- * Act on field_attach_submit.
+ * Act on field_attach_submit().
  *
  * This hook is invoked after the field module has performed the operation.
  *
  * See field_attach_submit() for details and arguments.
  */
 function hook_field_attach_submit($entity_type, $entity, $form, &$form_state) {
+  // @todo Needs function body.
 }
 
 /**
- * Act on field_attach_presave.
+ * Act on field_attach_presave().
  *
  * This hook is invoked after the field module has performed the operation.
  *
  * See field_attach_presave() for details and arguments.
  */
 function hook_field_attach_presave($entity_type, $entity) {
+  // @todo Needs function body.
 }
 
 /**
- * Act on field_attach_insert.
+ * Act on field_attach_insert().
  *
  * This hook is invoked after the field module has performed the operation.
  *
  * See field_attach_insert() for details and arguments.
  */
 function hook_field_attach_insert($entity_type, $entity) {
+  // @todo Needs function body.
 }
 
 /**
- * Act on field_attach_update.
+ * Act on field_attach_update().
  *
  * This hook is invoked after the field module has performed the operation.
  *
  * See field_attach_update() for details and arguments.
  */
 function hook_field_attach_update($entity_type, $entity) {
+  // @todo Needs function body.
 }
 
 /**
- * Act on field_attach_preprocess.
+ * Alter field_attach_preprocess() variables.
  *
- * This hook is invoked while preprocessing the field.tpl.php template file.
+ * This hook is invoked while preprocessing the field.tpl.php template file
+ * in field_attach_preprocess().
  *
  * @param $variables
  *   The variables array is passed by reference and will be populated with field
  *   values.
  * @param $context
  *   An associative array containing:
- *   - entity_type: The type of $entity; e.g. 'node' or 'user'.
- *   - object: The entity with fields to render.
+ *   - entity_type: The type of $entity; for example, 'node' or 'user'.
+ *   - entity: The entity with fields to render.
  *   - element: The structured array containing the values ready for rendering.
  */
 function hook_field_attach_preprocess_alter(&$variables, $context) {
+  // @todo Needs function body.
 }
 
 /**
- * Act on field_attach_delete.
+ * Act on field_attach_delete().
  *
  * This hook is invoked after the field module has performed the operation.
  *
  * See field_attach_delete() for details and arguments.
  */
 function hook_field_attach_delete($entity_type, $entity) {
+  // @todo Needs function body.
 }
 
 /**
- * Act on field_attach_delete_revision.
+ * Act on field_attach_delete_revision().
  *
  * This hook is invoked after the field module has performed the operation.
  *
  * See field_attach_delete_revision() for details and arguments.
  */
 function hook_field_attach_delete_revision($entity_type, $entity) {
+  // @todo Needs function body.
 }
 
 /**
- * Act on field_purge_data.
+ * Act on field_purge_data().
  *
  * 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
+ * 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'.
+ *   The type of $entity; for example, 'node' or 'user'.
  * @param $entity
  *   The pseudo-entity whose field data is being purged.
  * @param $field
@@ -1113,23 +1155,24 @@ function hook_field_attach_purge($entity_type, $entity, $field, $instance) {
 }
 
 /**
- * Act on field_attach_view.
+ * Perform alterations on field_attach_view().
  *
  * This hook is invoked after the field module has performed the operation.
  *
- * @param &$output
- *   The structured content array tree for all of $entity's fields.
+ * @param $output
+ *   The structured content array tree for all of the entity's fields.
  * @param $context
  *   An associative array containing:
- *   - entity_type: The type of $entity; e.g. 'node' or 'user'.
- *   - object: The entity with fields to render.
- *   - view_mode: View mode, e.g. 'full', 'teaser'...
+ *   - entity_type: The type of $entity; for example, 'node' or 'user'.
+ *   - entity: The entity with fields to render.
+ *   - view_mode: View mode, for example, 'full' or 'teaser'.
  */
 function hook_field_attach_view_alter(&$output, $context) {
+  // @todo Needs function body.
 }
 
 /**
- * Act on field_language().
+ * Perform alterations on field_language() values.
  *
  * This hook is invoked to alter the array of display languages for the given
  * entity.
@@ -1143,13 +1186,14 @@ function hook_field_attach_view_alter(&$output, $context) {
  *   - langcode: The language code $entity has to be displayed in.
  */
 function hook_field_language_alter(&$display_language, $context) {
+  // @todo Needs function body.
 }
 
 /**
- * Act on field_available_languages().
+ * Alter field_available_languages() values.
  *
- * This hook is invoked to alter the array of available languages for the given
- * field.
+ * This hook is invoked from field_available_languages() to allow modules 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.
@@ -1159,26 +1203,29 @@ function hook_field_language_alter(&$display_language, $context) {
  *   - field: A field data structure.
  */
 function hook_field_available_languages_alter(&$languages, $context) {
+  // @todo Needs function body.
 }
 
 /**
- * Act on field_attach_create_bundle.
+ * Act on field_attach_create_bundle().
  *
  * This hook is invoked after the field module has performed the operation.
  *
  * See field_attach_create_bundle() for details and arguments.
  */
 function hook_field_attach_create_bundle($entity_type, $bundle) {
+  // @todo Needs function body.
 }
 
 /**
- * Act on field_attach_rename_bundle.
+ * Act on field_attach_rename_bundle().
  *
  * This hook is invoked after the field module has performed the operation.
  *
  * See field_attach_rename_bundle() for details and arguments.
  */
 function hook_field_attach_rename_bundle($entity_type, $bundle_old, $bundle_new) {
+  // @todo Needs function body.
 }
 
 /**
@@ -1187,7 +1234,7 @@ function hook_field_attach_rename_bundle($entity_type, $bundle_old, $bundle_new)
  * This hook is invoked after the field module has performed the operation.
  *
  * @param $entity_type
- *   The type of entity; e.g. 'node' or 'user'.
+ *   The type of entity; for example, 'node' or 'user'.
  * @param $bundle
  *   The bundle that was just deleted.
  * @param $instances
@@ -1195,6 +1242,7 @@ function hook_field_attach_rename_bundle($entity_type, $bundle_old, $bundle_new)
  *   deleted.
  */
 function hook_field_attach_delete_bundle($entity_type, $bundle, $instances) {
+  // @todo Needs function body.
 }
 
 /**
@@ -1261,14 +1309,18 @@ function hook_field_storage_info_alter(&$info) {
  *
  * @param $field
  *   A field structure.
+ *
  * @return
  *   An array of details.
  *    - The first dimension is a store type (sql, solr, etc).
  *    - The second dimension indicates the age of the values in the store
  *      FIELD_LOAD_CURRENT or FIELD_LOAD_REVISION.
  *    - Other dimensions are specific to the field storage module.
+ *
+ * @see hook_field_storage_details_alter()
  */
 function hook_field_storage_details($field) {
+  // @todo Needs function body.
 }
 
 /**
@@ -1279,13 +1331,19 @@ function hook_field_storage_details($field) {
  *   hook_field_storage_details() implementations.
  * @param $field
  *   A field structure.
+ *
+ * @see hook_field_storage_details()
  */
 function hook_field_storage_details_alter(&$details, $field) {
+  // @todo Needs function body.
 }
 
 /**
  * Load field data for a set of entities.
  *
+ * This hook is invoked from field_attach_load() to ask the field storage
+ * module to load field data.
+ *
  * Modules implementing this hook should load field values and add them to
  * objects in $entities. Fields with no values should be added as empty
  * arrays.
@@ -1303,16 +1361,20 @@ function hook_field_storage_details_alter(&$details, $field) {
  *   depending on the $age parameter) to add each field to.
  * @param $options
  *   An associative array of additional options, with the following keys:
- *   - 'deleted': If TRUE, deleted fields should be loaded as well as
+ *   - deleted: If TRUE, deleted fields should be loaded as well as
  *     non-deleted fields. If unset or FALSE, only non-deleted fields should be
  *     loaded.
  */
-function hook_field_storage_load($entity_type, $entities, $age, $fields, $options) {
+function hook_field_storage_load($entity_type, &$entities, $age, $fields, $options) {
+  // @todo Needs function body.
 }
 
 /**
  * Write field data for an entity.
  *
+ * This hook is invoked from field_attach_insert() and field_attach_update(),
+ * to ask the field storage module to save field data.
+ *
  * @param $entity_type
  *   The entity type of entity, such as 'node' or 'user'.
  * @param $entity
@@ -1322,28 +1384,36 @@ function hook_field_storage_load($entity_type, $entities, $age, $fields, $option
  *   FIELD_STORAGE_INSERT when inserting a new entity.
  * @param $fields
  *   An array listing the fields to be written. The keys and values of the
- *   array are field ids.
+ *   array are field IDs.
  */
 function hook_field_storage_write($entity_type, $entity, $op, $fields) {
+  // @todo Needs function body.
 }
 
 /**
  * Delete all field data for an entity.
  *
+ * This hook is invoked from field_attach_delete() to ask the field storage
+ * module to delete field data.
+ *
  * @param $entity_type
  *   The entity type of entity, such as 'node' or 'user'.
  * @param $entity
  *   The entity on which to operate.
  * @param $fields
  *   An array listing the fields to delete. The keys and values of the
- *   array are field ids.
+ *   array are field IDs.
  */
 function hook_field_storage_delete($entity_type, $entity, $fields) {
+  // @todo Needs function body.
 }
 
 /**
  * Delete a single revision of field data for an entity.
  *
+ * This hook is invoked from field_attach_delete_revision() to ask the field
+ * storage module to delete field revision data.
+ *
  * Deleting the current (most recently written) revision is not
  * allowed as has undefined results.
  *
@@ -1351,58 +1421,76 @@ function hook_field_storage_delete($entity_type, $entity, $fields) {
  *   The entity type of entity, such as 'node' or 'user'.
  * @param $entity
  *   The entity on which to operate. The revision to delete is
- *   indicated by the entity's revision id property, as identified by
+ *   indicated by the entity's revision ID property, as identified by
  *   hook_fieldable_info() for $entity_type.
  * @param $fields
  *   An array listing the fields to delete. The keys and values of the
- *   array are field ids.
+ *   array are field IDs.
  */
 function hook_field_storage_delete_revision($entity_type, $entity, $fields) {
+  // @todo Needs function body.
 }
 
 /**
  * Handle a field query.
  *
+ * This hook is invoked from field_attach_query() to ask the field storage
+ * module to handle a field query.
+ *
  * @param $field_name
  *   The name of the field to query.
  * @param $conditions
- *   See field_attach_query().
- *   A storage module that doesn't support querying a given column should raise
- *   a FieldQueryException. Incompatibilities should be mentioned on the module
- *   project page.
+ *   See field_attach_query(). A storage module that doesn't support querying a
+ *   given column should raise a FieldQueryException. Incompatibilities should
+ *   be mentioned on the module project page.
  * @param $options
  *   See field_attach_query(). All option keys are guaranteed to be specified.
+ *
  * @return
  *   See field_attach_query().
  */
 function hook_field_storage_query($field_name, $conditions, $options) {
+  // @todo Needs function body
 }
 
 /**
  * Act on creation of a new field.
  *
+ * This hook is invoked from field_create_field() to ask the field storage
+ * module to save field information and prepare for storing field instances.
+ * If there is a problem, the field storage module should throw an exception.
+ *
  * @param $field
  *   The field structure being created.
  */
 function hook_field_storage_create_field($field) {
+  // @todo Needs function body.
 }
 
 /**
  * Act on deletion of a field.
  *
+ * This hook is invoked from field_delete_field() to ask the field storage
+ * module to mark all information stored in the field for deletion.
+ *
  * @param $field
  *   The field being deleted.
  */
 function hook_field_storage_delete_field($field) {
+  // @todo Needs function body.
 }
 
 /**
  * Act on deletion of a field instance.
  *
+ * This hook is invoked from field_delete_instance() to ask the field storage
+ * module to mark all information stored for the field instance for deletion.
+ *
  * @param $instance
  *   The instance being deleted.
  */
 function hook_field_storage_delete_instance($instance) {
+  // @todo Needs function body.
 }
 
 /**
@@ -1432,13 +1520,14 @@ function hook_field_storage_delete_instance($instance) {
  *   that your module has already loaded a field.
  * @param $options
  *   An associative array of additional options, with the following keys:
- *   - 'field_id': The field ID that should be loaded. If unset, all fields
+ *   - field_id: The field ID that should be loaded. If unset, all fields
  *     should be loaded.
- *   - 'deleted': If TRUE, deleted fields should be loaded as well as
+ *   - deleted: If TRUE, deleted fields should be loaded as well as
  *     non-deleted fields. If unset or FALSE, only non-deleted fields should be
  *     loaded.
  */
 function hook_field_storage_pre_load($entity_type, $entities, $age, &$skip_fields, $options) {
+  // @todo Needs function body.
 }
 
 /**
@@ -1448,15 +1537,15 @@ function hook_field_storage_pre_load($entity_type, $entities, $age, &$skip_field
  * optionally preventing the field storage module from doing so.
  *
  * @param $entity_type
- *   The type of $entity; e.g. 'node' or 'user'.
+ *   The type of $entity; for example, 'node' or 'user'.
  * @param $entity
  *   The entity with fields to save.
  * @param $skip_fields
- *   An array keyed by field ids whose data has already been written and
- *   therefore should not be written again. The values associated to these keys
- *   are not specified.
+ *   An array keyed by field IDs whose data has already been written and
+ *   therefore should not be written again. The values associated with these
+ *   keys are not specified.
  * @return
- *   Saved field ids are set set as keys in $skip_fields.
+ *   Saved field IDs are set set as keys in $skip_fields.
  */
 function hook_field_storage_pre_insert($entity_type, $entity, &$skip_fields) {
   if ($entity_type == 'node' && $entity->status && _forum_node_check_node_type($entity)) {
@@ -1485,15 +1574,15 @@ function hook_field_storage_pre_insert($entity_type, $entity, &$skip_fields) {
  * optionally preventing the field storage module from doing so.
  *
  * @param $entity_type
- *   The type of $entity; e.g. 'node' or 'user'.
+ *   The type of $entity; for example, 'node' or 'user'.
  * @param $entity
  *   The entity with fields to save.
  * @param $skip_fields
- *   An array keyed by field ids whose data has already been written and
- *   therefore should not be written again. The values associated to these keys
- *   are not specified.
+ *   An array keyed by field IDs whose data has already been written and
+ *   therefore should not be written again. The values associated with these
+ *   keys are not specified.
  * @return
- *   Saved field ids are set set as keys in $skip_fields.
+ *   Saved field IDs are set set as keys in $skip_fields.
  */
 function hook_field_storage_pre_update($entity_type, $entity, &$skip_fields) {
   $first_call = &drupal_static(__FUNCTION__, array());
@@ -1555,6 +1644,7 @@ function hook_field_storage_pre_update($entity_type, $entity, &$skip_fields) {
  *   handled.
  */
 function hook_field_storage_pre_query($field_name, $conditions, $options, &$skip_field) {
+  // @todo Needs function body.
 }
 
 /**
@@ -1573,27 +1663,27 @@ function hook_field_storage_pre_query($field_name, $conditions, $options, &$skip
 /**
  * Act on a field being created.
  *
- * This hook is invoked after the field is created and so it cannot modify the
- * field itself.
- *
- * TODO: Not implemented.
+ * This hook is invoked from field_create_field() after the field is created, to
+ * allow modules to act on field creation.
  *
  * @param $field
  *   The field just created.
  */
 function hook_field_create_field($field) {
+  // @todo Needs function body.
 }
 
 /**
  * Act on a field instance being created.
  *
- * This hook is invoked after the instance record is saved and so it cannot
- * modify the instance itself.
+ * This hook is invoked from field_create_instance() after the instance record
+ * is saved, so it cannot be used to modify the instance itself.
  *
  * @param $instance
  *   The instance just created.
  */
 function hook_field_create_instance($instance) {
+  // @todo Needs function body.
 }
 
 /**
@@ -1606,16 +1696,16 @@ function hook_field_create_instance($instance) {
  * semantics, or if there are external dependencies on field settings
  * that cannot be updated.
  *
+ * To forbid the update from occurring, throw a FieldUpdateForbiddenException.
+ *
  * @param $field
  *   The field as it will be post-update.
  * @param $prior_field
  *   The field as it is pre-update.
  * @param $has_data
  *   Whether any data already exists for this field.
- * @return
- *   Throws a FieldUpdateForbiddenException to prevent the update from occurring.
  */
-function hook_field_update_field_forbid($field, $prior_field, $has_data) {
+function hook_field_update_forbid($field, $prior_field, $has_data) {
   // A 'list' field stores integer keys mapped to display values. If
   // the new field will have fewer values, and any data exists for the
   // abandoned keys, the field will have no way to display them. So,
@@ -1634,7 +1724,7 @@ function hook_field_update_field_forbid($field, $prior_field, $has_data) {
 /**
  * Act on a field being updated.
  *
- * This hook is invoked just after field is updated.
+ * This hook is invoked just after field is updated in field_update_field().
  *
  * @param $field
  *   The field as it is post-update.
@@ -1644,24 +1734,26 @@ function hook_field_update_field_forbid($field, $prior_field, $has_data) {
  *   Whether any data already exists for this field.
  */
 function hook_field_update_field($field, $prior_field, $has_data) {
+  // @todo Needs function body.
 }
 
 /**
  * Act on a field being deleted.
  *
- * This hook is invoked just after field is deleted.
+ * This hook is invoked just after a field is deleted by field_delete_field().
  *
  * @param $field
  *   The field just deleted.
  */
 function hook_field_delete_field($field) {
+  // @todo Needs function body.
 }
 
 /**
  * Act on a field instance being updated.
  *
- * This hook is invoked after the instance record is saved and so it cannot
- * modify the instance itself.
+ * This hook is invoked from field_update_instance() after the instance record
+ * is saved, so it cannot be used by a module to modify the instance itself.
  *
  * @param $instance
  *   The instance as it is post-update.
@@ -1669,35 +1761,44 @@ function hook_field_delete_field($field) {
  *   The instance as it was pre-update.
  */
 function hook_field_update_instance($instance, $prior_instance) {
+  // @todo Needs function body.
 }
 
 /**
  * Act on a field instance being deleted.
  *
- * This hook is invoked just after the instance is deleted.
+ * This hook is invoked from field_delete_instance() after the instance is
+ * deleted.
  *
  * @param $instance
  *   The instance just deleted.
  */
 function hook_field_delete_instance($instance) {
+  // @todo Needs function body.
 }
 
 /**
  * Act on field records being read from the database.
  *
+ * This hook is invoked from field_read_fields() on each field being read.
+ *
  * @param $field
  *   The field record just read from the database.
  */
-function hook_field_read_field($field) {
+function hook_field_read_field(&$field) {
+  // @todo Needs function body.
 }
 
 /**
  * Act on a field record being read from the database.
  *
+ * This hook is invoked from field_read_instances() on each instance being read.
+ *
  * @param $instance
  *   The instance record just read from the database.
  */
 function hook_field_read_instance($instance) {
+  // @todo Needs function body.
 }
 
 /**
@@ -1775,7 +1876,7 @@ function hook_field_storage_purge_field_instance($instance) {
  * module to delete field data information.
  *
  * @param $entity_type
- *   The type of $entity; e.g. 'node' or 'user'.
+ *   The type of $entity; for example, 'node' or 'user'.
  * @param $entity
  *   The pseudo-entity whose field data to delete.
  * @param $field
@@ -1810,40 +1911,23 @@ function hook_field_storage_purge($entity_type, $entity, $field, $instance) {
 /**
  * Determine whether the user has access to a given field.
  *
+ * This hook is invoked from field_access() to let modules block access to
+ * operations on fields. If no module returns FALSE, the operation is allowed.
+ *
  * @param $op
- *   The operation to be performed. Possible values:
- *   - "edit"
- *   - "view"
+ *   The operation to be performed. Possible values: 'edit', 'view'.
  * @param $field
  *   The field on which the operation is to be performed.
  * @param $entity_type
- *   The type of $entity; e.g. 'node' or 'user'.
+ *   The type of $entity; for example, 'node' or 'user'.
  * @param $entity
  *   (optional) The entity for the operation.
  * @param $account
- *   (optional) The account to check, if not given use currently logged in user.
+ *   (optional) The account to check; if not given use currently logged in user.
+ *
  * @return
- *   TRUE if the operation is allowed;
- *   FALSE if the operation is denied.
+ *   TRUE if the operation is allowed, and FALSE if the operation is denied.
  */
 function hook_field_access($op, $field, $entity_type, $entity, $account) {
-}
-
-/**
- * Allows a module to object to a field definition update.
- *
- * The module should throw a FieldUpdateForbiddenException to indicate
- * that the update should not proceed.
- *
- * @param $field
- *   The updated field structure that a module is attempting to save.
- * @param $prior_field
- *   The currently-saved field structure.
- * @param $has_data
- *   TRUE if the field has data in storage currently.
- */
-function hook_field_update_forbid($field, $prior_field, $has_data) {
-  if ($has_data && $field['columns'] != $prior_field['columns']) {
-    throw new FieldUpdateForbiddenException("field_sql_storage cannot change the schema for an existing field with data.");
-  }
+  // @todo Needs function body.
 }
diff --git a/modules/field/modules/field_sql_storage/field_sql_storage.module b/modules/field/modules/field_sql_storage/field_sql_storage.module
index a768aa9c0..74cc5564c 100644
--- a/modules/field/modules/field_sql_storage/field_sql_storage.module
+++ b/modules/field/modules/field_sql_storage/field_sql_storage.module
@@ -218,7 +218,7 @@ function field_sql_storage_field_storage_create_field($field) {
 }
 
 /**
- * Implements hook_field_update_field_forbid().
+ * Implements hook_field_update_forbid().
  *
  * Forbid any field update that changes column definitions if there is
  * any data.