diff --git a/core/modules/field/field.api.php b/core/modules/field/field.api.php
index d9061e1..3384066 100644
--- a/core/modules/field/field.api.php
+++ b/core/modules/field/field.api.php
@@ -6,7 +6,7 @@
  */
 
 /**
- * Exposes "pseudo-field" components on fieldable entities.
+ * Expose "pseudo-field" components on fieldable entities.
  *
  * Field UI's "Manage fields" and "Manage display" pages let users re-order
  * fields, but also non-field components. For nodes, these include the title,
@@ -15,16 +15,16 @@
  *
  * Fieldable entities or modules that want to have their components supported
  * should expose them using this hook. The user-defined settings (weight,
- * visible) are automatically applied on rendered forms and displayed
- * entities in a #pre_render callback added by field_attach_form() and
+ * visible) are automatically applied on rendered forms and displayed entities
+ * in a #pre_render callback added by field_attach_form() and
  * field_attach_view().
  *
  * @see _field_extra_fields_pre_render()
  * @see hook_field_extra_fields_alter()
  *
  * @return
- *   A nested array of 'pseudo-field' components. Each list is nested within
- *   the following keys: entity type, bundle name, context (either 'form' or
+ *   A nested array of 'pseudo-field' components. Each list is nested within the
+ *   following keys: entity type, bundle name, context (either 'form' or
  *   'display'). The keys are the name of the elements as appearing in the
  *   renderable array (either the entity form or the displayed entity). The
  *   value is an associative array:
@@ -83,7 +83,7 @@ function hook_field_extra_fields_alter(&$info) {
 /**
  * @defgroup field_types Field Types API
  * @{
- * Define field types.
+ * Define field types, widget types, display formatter types, storage types.
  *
  * In the Field API, each field has a type, which determines what kind of data
  * (integer, string, date, etc.) the field can hold, which settings it provides,
@@ -97,7 +97,7 @@ function hook_field_extra_fields_alter(&$info) {
  * appears in edit forms, while @link field_formatter formatters @endlink
  * specify how the field appears in displayed entities.
  *
- * A third kind of pluggable handlers, storage backends, is defined by the
+ * A third kind of pluggable handler, storage backends, is defined by the
  * @link field_storage Field Storage API @endlink.
  *
  * See @link field Field API @endlink for information about the other parts of
@@ -124,10 +124,10 @@ function hook_field_extra_fields_alter(&$info) {
  *     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
- *     type is available (i.e. provided by the field type module, or by a module
- *     the field type module depends on).
+ *     instances of this field type, when no widget is specified in the instance
+ *     definition. This widget 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).
  *   - default_formatter: The machine name of the default formatter to be used
  *     by instances of this field type, when no formatter is specified in the
  *     instance definition. This formatter must be available whenever the field
@@ -209,14 +209,13 @@ function hook_field_info_alter(&$info) {
  *     settings when possible. No assumptions should be made on how storage
  *     engines internally use the original column name to structure their
  *     storage.
- *   - indexes: (optional) An array of Schema API indexes definitions. Only
+ *   - indexes: (optional) An array of Schema API index 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
+ *     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.
- *   - foreign keys: (optional) An array of Schema API foreign keys
- *     definitions.
+ *   - foreign keys: (optional) An array of Schema API foreign key definitions.
  */
 function hook_field_schema($field) {
   if ($field['type'] == 'text_long') {
@@ -313,8 +312,8 @@ function hook_field_load($entity_type, $entities, $field, $instances, $langcode,
 /**
  * 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
+ * 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().
  *
  * Unlike most other field hooks, this hook operates on multiple entities. The
@@ -335,7 +334,7 @@ function hook_field_load($entity_type, $entities, $field, $instances, $langcode,
  *   Array of instance structures for $field for each entity, keyed by entity
  *   ID.
  * @param $langcode
- *   The language associated to $items.
+ *   The language associated with $items.
  * @param $items
  *   $entity->{$field['field_name']}, or an empty array if unset.
  */
@@ -379,7 +378,7 @@ function hook_field_prepare_view($entity_type, $entities, $field, $instances, $l
  *   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.
+ *   - 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) {
@@ -597,9 +596,9 @@ function hook_field_delete($entity_type, $entity, $field, $instance, $langcode,
 /**
  * Define custom revision delete behavior for this module's field types.
  *
- * 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.
+ * 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.
@@ -637,7 +636,7 @@ function hook_field_delete_revision($entity_type, $entity, $field, $instance, $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 $source_entity
@@ -665,8 +664,8 @@ function hook_field_prepare_translation($entity_type, $entity, $field, $instance
  *   The field to which $item belongs.
  *
  * @return
- *   TRUE if $field's type considers $item not to contain any data;
- *   FALSE otherwise.
+ *   TRUE if $field's type considers $item not to contain any data; FALSE
+ *   otherwise.
  */
 function hook_field_is_empty($item, $field) {
   if (empty($item['value']) && (string) $item['value'] !== '0') {
@@ -705,30 +704,28 @@ function hook_field_is_empty($item, $field) {
  * Expose Field API widget types.
  *
  * @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:
+ *   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.
- *   - description: A short description for the widget type.
+ *   - description: A short description of the widget type.
  *   - field types: An array of field types the widget supports.
- *   - 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: An array whose keys are the names of the settings available to
+ *     the widget type, and whose values are the default values for those
  *     settings.
  *   - 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
+ *       - FIELD_BEHAVIOR_DEFAULT: (default) 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: A 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.
+ *       - FIELD_BEHAVIOR_DEFAULT: (default) The widget accepts default values.
+ *       - FIELD_BEHAVIOR_NONE: The widget does not support default values.
  *
  * @see hook_field_widget_info_alter()
  * @see hook_field_widget_form()
@@ -793,23 +790,23 @@ function hook_field_widget_info_alter(&$info) {
  * contains the base form element properties derived from the field
  * configuration.
  *
- * Field API will set the weight, field name and delta values for each form
+ * 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
  * invoke this hook as many times as needed.
  *
  * Note that, depending on the context in which the widget is being included
- * (regular entity form, field configuration form, advanced search form...),
- * the values for $field and $instance might be different from the "official"
+ * (regular entity form, field configuration form, advanced search form...), the
+ * values for $field and $instance might be different from the "official"
  * definitions returned by field_info_field() and field_info_instance().
- * Examples: mono-value widget even if the field is multi-valued, non-required
- * widget even if the field is 'required'...
+ * Examples: a single-value widget even if the field is multi-valued, a 
+ * non-required widget even if the field is 'required'...
  *
  * Therefore, the FAPI element callbacks (such as #process, #element_validate,
- * #value_callback...) used by the widget cannot use the field_info_field()
- * or field_info_instance() functions to retrieve the $field or $instance
+ * #value_callback...) used by the widget cannot use the field_info_field() or
+ * field_info_instance() functions to retrieve the $field or $instance
  * definitions they should operate on. The field_widget_field() and
- * field_widget_instance() functions should be used instead to fetch the
- * current working definitions from $form_state, where Field API stores them.
+ * field_widget_instance() functions should be used instead to fetch the current
+ * working definitions from $form_state, where Field API stores them.
  *
  * Alternatively, hook_field_widget_form() can extract the needed specific
  * properties from $field and $instance and set them as ad-hoc
@@ -819,8 +816,8 @@ function hook_field_widget_info_alter(&$info) {
  * hook_field_widget_form_alter().
  *
  * @param $form
- *   The form structure where widgets are being attached to. This might be a
- *   full form structure, or a sub-element of a larger form.
+ *   The form structure widgets are being attached to. This might be a full form
+ *   structure, or a sub-element of a larger form.
  * @param $form_state
  *   An associative array containing the current state of the form.
  * @param $field
@@ -840,11 +837,10 @@ function hook_field_widget_info_alter(&$info) {
  *   - #field_name: The name of the field.
  *   - #language: The language the field is being edited in.
  *   - #field_parents: The 'parents' space for the field in the form. Most
- *       widgets can simply overlook this property. This identifies the
- *       location where the field values are placed within
- *       $form_state['values'], and is used to access processing information
- *       for the field through the field_form_get_state() and
- *       field_form_set_state() functions.
+ *       widgets can simply overlook this property. This identifies the location
+ *       where the field values are placed within $form_state['values'], and is
+ *       used to access processing information for the field through the
+ *       field_form_get_state() and field_form_set_state() functions.
  *   - #columns: A list of field storage columns of the field.
  *   - #title: The sanitized element label for the field instance, ready for
  *     output.
@@ -882,14 +878,13 @@ function hook_field_widget_form(&$form, &$form_state, $field, $instance, $langco
  * @param $context
  *   An associative array containing the following key-value pairs, matching the
  *   arguments received by hook_field_widget_form():
- *   - "form": The form structure where widgets are being attached to. This
- *     might be a full form structure, or a sub-element of a larger form.
- *   - "field": The field structure.
- *   - "instance": The field instance structure.
- *   - "langcode": The language associated with $items.
- *   - "items": Array of default values for this field.
- *   - "delta": The order of this item in the array of subelements (0, 1, 2,
- *     etc).
+ *   - form: The form structure widgets are being attached to. This might be a
+ *     full form structure, or a sub-element of a larger form.
+ *   - field: The field structure.
+ *   - instance: The field instance structure.
+ *   - langcode: The language associated with $items.
+ *   - items: Array of default values for this field.
+ *   - delta: The order of this item in the array of subelements (0, 1, 2, etc).
  *
  * @see hook_field_widget_form()
  * @see hook_field_widget_WIDGET_TYPE_form_alter
@@ -916,14 +911,13 @@ function hook_field_widget_form_alter(&$element, &$form_state, $context) {
  * @param $context
  *   An associative array containing the following key-value pairs, matching the
  *   arguments received by hook_field_widget_form():
- *   - "form": The form structure where widgets are being attached to. This
- *     might be a full form structure, or a sub-element of a larger form.
- *   - "field": The field structure.
- *   - "instance": The field instance structure.
- *   - "langcode": The language associated with $items.
- *   - "items": Array of default values for this field.
- *   - "delta": The order of this item in the array of subelements (0, 1, 2,
- *     etc).
+ *   - form: The form structure widgets are being attached to. This might be a
+ *     full form structure, or a sub-element of a larger form.
+ *   - field: The field structure.
+ *   - instance: The field instance structure.
+ *   - langcode: The language associated with $items.
+ *   - items: Array of default values for this field.
+ *   - delta: The order of this item in the array of subelements (0, 1, 2, etc).
  *
  * @see hook_field_widget_form()
  * @see hook_field_widget_form_alter()
@@ -945,12 +939,12 @@ function hook_field_widget_WIDGET_TYPE_form_alter(&$element, &$form_state, $cont
  * @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 structure where field elements are attached to. This might be a
- *   full form structure, or a sub-element of a larger form.
+ *   The form structure field elements are attached to. This might be a full
+ *   form structure, or a sub-element of a larger form.
  * @param $form_state
  *   An associative array containing the current state of the form.
  */
@@ -989,17 +983,17 @@ function hook_field_widget_error($element, $error, $form, &$form_state) {
  * field_attach_view() functions.
  *
  * @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
+ *   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.
- *   - description: A short description for the formatter type.
+ *   - description: A short description of the formatter type.
  *   - field types: An array of field types the formatter supports.
- *   - 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.
+ *   - settings: An array whose keys are the names of the settings available to
+ *     the formatter type, and whose values are the default values for those
+ *     settings.
  *
  * @see hook_field_formatter_info_alter()
  * @see hook_field_formatter_view()
@@ -1059,7 +1053,7 @@ function hook_field_formatter_info_alter(&$info) {
  *
  * This should be used when a formatter needs to load additional information
  * from the database in order to render a field, for example a reference field
- * which displays properties of the referenced entities such as name or type.
+ * that 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().
  *
@@ -1068,6 +1062,9 @@ function hook_field_formatter_info_alter(&$info) {
  * For performance reasons, information for all available entities should be
  * loaded in a single query where possible.
  *
+ * Changes or additions to field values are done by alterings the $items
+ * parameter by reference.
+ *
  * @param $entity_type
  *   The type of $entity.
  * @param $entities
@@ -1084,10 +1081,6 @@ function hook_field_formatter_info_alter(&$info) {
  *   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.
- *
- * @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) {
   $tids = array();
@@ -1146,13 +1139,13 @@ function hook_field_formatter_prepare_view($entity_type, $entities, $field, $ins
  *   Array of values for this field.
  * @param $display
  *   The display settings to use, as found in the 'display' entry of instance
- *   definitions. The array notably contains the following keys and values;
+ *   definitions. The array notably contains the following keys and values:
  *   - type: The name of the formatter to use.
  *   - settings: The array of formatter settings.
  *
  * @return
- *   A renderable array for the $items, as an array of child elements keyed
- *   by numeric indexes starting from 0.
+ *   A renderable array for $items, as an array of child elements keyed by
+ *   numeric indexes starting from 0.
  */
 function hook_field_formatter_view($entity_type, $entity, $field, $instance, $langcode, $items, $display) {
   $element = array();
@@ -1218,18 +1211,18 @@ function hook_field_formatter_view($entity_type, $entity, $field, $instance, $la
  * @param $entity
  *   The entity for which an edit form is being built.
  * @param $form
- *   The form structure where field elements are attached to. This might be a
- *   full form structure, or a sub-element of a larger form. The
- *   $form['#parents'] property can be used to identify the corresponding part
- *   of $form_state['values']. Hook implementations that need to act on the
+ *   The form structure field elements are attached to. This might be a full
+ *   form structure, or a sub-element of a larger form. The $form['#parents']
+ *   property can be used to identify the corresponding part of
+ *   $form_state['values']. Hook implementations that need to act on the
  *   top-level properties of the global form (like #submit, #validate...) can
  *   add a #process callback to the array received in the $form parameter, and
  *   act on the $complete_form parameter in the process callback.
  * @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.
+ *   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) {
   // Add a checkbox allowing a given field to be emptied.
@@ -1264,7 +1257,17 @@ function hook_field_attach_load($entity_type, $entities, $age, $options) {
  *
  * This hook is invoked after the field module has performed the operation.
  *
- * See field_attach_validate() for details and arguments.
+ * @param $entity_type
+ *   The type of $entity; e.g. 'node' or 'user'.
+ * @param $entity
+ *   The entity with fields to validate.
+ * @param $errors
+ *   The array of errors (keyed by field name, language code, and delta) that
+ *   have 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.
  */
 function hook_field_attach_validate($entity_type, $entity, &$errors) {
   // @todo Needs function body.
@@ -1281,8 +1284,8 @@ function hook_field_attach_validate($entity_type, $entity, &$errors) {
  *   The entity for which an edit form is being submitted. The incoming form
  *   values have been extracted as field values of the $entity object.
  * @param $form
- *   The form structure where field elements are attached to. This might be a
- *   full form structure, or a sub-part of a larger form. The $form['#parents']
+ *   The form structure field elements are attached to. This might be a full
+ *   form structure, or a sub-part of a larger form. The $form['#parents']
  *   property can be used to identify the corresponding part of
  *   $form_state['values'].
  * @param $form_state
@@ -1302,7 +1305,10 @@ function hook_field_attach_submit($entity_type, $entity, $form, &$form_state) {
  *
  * This hook is invoked after the field module has performed the operation.
  *
- * See field_attach_presave() for details and arguments.
+ * @param $entity_type
+ *   The type of $entity; e.g. 'node' or 'user'.
+ * @param $entity
+ *   The entity with fields to process
  */
 function hook_field_attach_presave($entity_type, $entity) {
   // @todo Needs function body.
@@ -1313,7 +1319,10 @@ function hook_field_attach_presave($entity_type, $entity) {
  *
  * This hook is invoked after the field module has performed the operation.
  *
- * See field_attach_insert() for details and arguments.
+ * @param $entity_type
+ *   The type of $entity; e.g. 'node' or 'user'.
+ * @param $entity
+ *   The entity with fields to process
  */
 function hook_field_attach_insert($entity_type, $entity) {
   // @todo Needs function body.
@@ -1324,7 +1333,10 @@ function hook_field_attach_insert($entity_type, $entity) {
  *
  * This hook is invoked after the field module has performed the operation.
  *
- * See field_attach_update() for details and arguments.
+ * @param $entity_type
+ *   The type of $entity; e.g. 'node' or 'user'.
+ * @param $entity
+ *   The entity with fields to process
  */
 function hook_field_attach_update($entity_type, $entity) {
   // @todo Needs function body.
@@ -1333,8 +1345,8 @@ function hook_field_attach_update($entity_type, $entity) {
 /**
  * Alter field_attach_preprocess() variables.
  *
- * This hook is invoked while preprocessing the field.tpl.php template file
- * in field_attach_preprocess().
+ * 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
@@ -1354,7 +1366,10 @@ function hook_field_attach_preprocess_alter(&$variables, $context) {
  *
  * This hook is invoked after the field module has performed the operation.
  *
- * See field_attach_delete() for details and arguments.
+ * @param $entity_type
+ *   The type of $entity; e.g. 'node' or 'user'.
+ * @param $entity
+ *   The entity with fields to process
  */
 function hook_field_attach_delete($entity_type, $entity) {
   // @todo Needs function body.
@@ -1365,7 +1380,10 @@ function hook_field_attach_delete($entity_type, $entity) {
  *
  * This hook is invoked after the field module has performed the operation.
  *
- * See field_attach_delete_revision() for details and arguments.
+ * @param $entity_type
+ *   The type of $entity; e.g. 'node' or 'user'.
+ * @param $entity
+ *   The entity with fields to process
  */
 function hook_field_attach_delete_revision($entity_type, $entity) {
   // @todo Needs function body.
@@ -1376,8 +1394,8 @@ function hook_field_attach_delete_revision($entity_type, $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.
+ * 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; for example, 'node' or 'user'.
@@ -1413,9 +1431,9 @@ function hook_field_attach_purge($entity_type, $entity, $field, $instance) {
  *   - display: Either a view mode string or an array of display settings. If
  *     this hook is being invoked from field_attach_view(), the 'display'
  *     element is set to the view mode string. If this hook is being invoked
- *     from field_view_field(), this element is set to the $display argument
- *     and the view_mode element is set to '_custom'. See field_view_field()
- *     for more information on what its $display argument contains.
+ *     from field_view_field(), this element is set to the $display argument and
+ *     the view_mode element is set to '_custom'. See field_view_field() for
+ *     more information on what its $display argument contains.
  *   - language: The language code used for rendering.
  */
 function hook_field_attach_view_alter(&$output, $context) {
@@ -1446,9 +1464,9 @@ function hook_field_attach_view_alter(&$output, $context) {
  * @param $context
  *   An associative array containing:
  *   - entity_type: The type of $entity; e.g. 'node' or 'user'.
- *   - langcode: The language the entity has to be translated in.
+ *   - langcode: The language the entity will be translated to.
  *   - source_entity: The entity holding the field values to be translated.
- *   - source_langcode: The source language from which translate.
+ *   - source_langcode: The source language from which to translate.
  */
 function hook_field_attach_prepare_translation_alter(&$entity, $context) {
   if ($context['entity_type'] == 'custom_entity_type') {
@@ -1505,7 +1523,10 @@ function hook_field_available_languages_alter(&$langcodes, $context) {
  *
  * This hook is invoked after the field module has performed the operation.
  *
- * See field_attach_create_bundle() for details and arguments.
+ * @param $entity_type
+ *   The type of $entity; e.g. 'node' or 'user'.
+ * @param $entity
+ *   The entity with fields to process
  */
 function hook_field_attach_create_bundle($entity_type, $bundle) {
   // When a new bundle is created, the menu needs to be rebuilt to add the
@@ -1518,7 +1539,12 @@ function hook_field_attach_create_bundle($entity_type, $bundle) {
  *
  * This hook is invoked after the field module has performed the operation.
  *
- * See field_attach_rename_bundle() for details and arguments.
+ * @param $entity_type
+ *   The entity type to which the bundle is bound.
+ * @param $bundle_old
+ *   The previous name of the bundle.
+ * @param $bundle_new
+ *   The new name of the bundle.
  */
 function hook_field_attach_rename_bundle($entity_type, $bundle_old, $bundle_new) {
   // Update the extra weights variable with new information.
@@ -1567,16 +1593,16 @@ function hook_field_attach_delete_bundle($entity_type, $bundle, $instances) {
  * Expose Field API storage backends.
  *
  * @return
- *   An array describing the storage backends implemented by the module.
- *   The keys are storage backend names. To avoid name clashes, storage backend
- *   names should be prefixed with the name of the module that exposes them.
- *   The values are arrays describing the storage backend, with the following
+ *   An array describing the storage backends implemented by the module. The
+ *   keys are storage backend names. To avoid name clashes, storage backend
+ *   names should be prefixed with the name of the module that exposes them. The
+ *   values are arrays describing the storage backend, with the following
  *   key/value pairs:
  *   - label: The human-readable name of the storage backend.
  *   - description: A short description for the storage backend.
- *   - settings: An array whose keys are the names of the settings available
- *     for the storage backend, and whose values are the default values for
- *     those settings.
+ *   - settings: An array whose keys are the names of the settings available to
+ *     the storage backend, and whose values are the default values of those
+ *     settings.
  */
 function hook_field_storage_info() {
   return array(
@@ -1609,8 +1635,8 @@ function hook_field_storage_info_alter(&$info) {
  * the table. A key/value storage module might return the server name,
  * authentication credentials, and bin name.
  *
- * Field storage modules are not obligated to implement this hook. Modules
- * that rely on these details must only use them for read operations.
+ * Field storage modules are not obligated to implement this hook. Modules that
+ * rely on these details must only use them for read operations.
  *
  * @param $field
  *   A field structure.
@@ -1675,12 +1701,11 @@ function hook_field_storage_details_alter(&$details, $field) {
 /**
  * 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.
+ * 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.
+ * objects in $entities. Fields with no values should be added as empty arrays.
  *
  * @param $entity_type
  *   The type of entity, such as 'node' or 'user'.
@@ -1695,9 +1720,8 @@ 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
- *     non-deleted fields. If unset or FALSE, only non-deleted fields should be
- *     loaded.
+ *   - 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) {
   $field_info = field_info_field_by_ids();
@@ -1747,8 +1771,8 @@ function hook_field_storage_load($entity_type, $entities, $age, $fields, $option
 /**
  * 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.
+ * 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'.
@@ -1758,8 +1782,8 @@ function hook_field_storage_load($entity_type, $entities, $age, $fields, $option
  *   FIELD_STORAGE_UPDATE when updating an existing entity,
  *   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.
+ *   An array listing the fields to be written. The keys and values of the array
+ *   are field IDs.
  */
 function hook_field_storage_write($entity_type, $entity, $op, $fields) {
   list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity);
@@ -1852,8 +1876,8 @@ function hook_field_storage_write($entity_type, $entity, $op, $fields) {
  * @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.
+ *   An array listing the fields to delete. The keys and values of the array
+ *   are field IDs.
  */
 function hook_field_storage_delete($entity_type, $entity, $fields) {
   list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity);
@@ -1872,18 +1896,18 @@ function hook_field_storage_delete($entity_type, $entity, $fields) {
  * 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.
+ * Deleting the current (most recently written) revision is not allowed as it
+ * has undefined results.
  *
  * @param $entity_type
  *   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
- *   hook_fieldable_info() for $entity_type.
+ *   The entity on which to operate. The revision to delete is 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.
+ *   An array listing the fields to delete. The keys and values of the array are
+ *   field IDs.
  */
 function hook_field_storage_delete_revision($entity_type, $entity, $fields) {
   list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity);
@@ -2020,8 +2044,8 @@ function hook_field_storage_query($query) {
  * 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.
+ * 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.
@@ -2092,13 +2116,13 @@ function hook_field_storage_delete_instance($instance) {
  * This hook allows modules to load data before the Field Storage API,
  * optionally preventing the field storage module from doing so.
  *
- * This lets 3rd party modules override, mirror, shard, or otherwise store a
- * subset of fields in a different way than the current storage engine.
- * Possible use cases include per-bundle storage, per-combo-field storage, etc.
+ * This lets 3rd party modules override, mirror, share, or otherwise store a
+ * subset of fields in a different way than the current storage engine. Possible
+ * use cases include per-bundle storage, per-combo-field storage, etc.
  *
  * 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. In addition, fields loaded should be added as keys to $skip_fields.
+ * objects in $entities. Fields with no values should be added as empty arrays.
+ * In addition, fields loaded should be added as keys to $skip_fields.
  *
  * @param $entity_type
  *   The type of entity, such as 'node' or 'user'.
@@ -2113,11 +2137,10 @@ 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
- *     should be loaded.
- *   - 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.
+ *   - 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 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.
@@ -2240,7 +2263,7 @@ function hook_field_info_max_weight($entity_type, $bundle, $context) {
 }
 
 /**
- * Alters the display settings of a field before it gets displayed.
+ * Alters the display settings of a field before it is displayed.
  *
  * Note that instead of hook_field_display_alter(), which is called for all
  * fields on all entity types, hook_field_display_ENTITY_TYPE_alter() may be
@@ -2275,7 +2298,7 @@ function hook_field_display_alter(&$display, $context) {
 }
 
 /**
- * Alters the display settings of a field on a given entity type before it gets displayed.
+ * Alters the display settings of a field before it is displayed.
  *
  * Modules can implement hook_field_display_ENTITY_TYPE_alter() to alter display
  * settings for fields on a specific entity type, rather than implementing
@@ -2313,8 +2336,8 @@ function hook_field_display_ENTITY_TYPE_alter(&$display, $context) {
  * cache the information.
  *
  * @param $displays
- *   An array of display settings for the pseudo-fields in the entity, keyed
- *   by pseudo-field names.
+ *   An array of display settings for the pseudo-fields in the entity, keyed by
+ *   pseudo-field names.
  * @param $context
  *   An associative array containing:
  *   - entity_type: The entity type; e.g., 'node' or 'user'.
@@ -2328,15 +2351,15 @@ function hook_field_extra_fields_display_alter(&$displays, $context) {
 }
 
 /**
- * Alters the widget properties of a field instance before it gets displayed.
+ * Alters the widget properties of a field instance before it is displayed.
  *
  * Note that instead of hook_field_widget_properties_alter(), which is called
  * for all fields on all entity types,
  * hook_field_widget_properties_ENTITY_TYPE_alter() may be used to alter widget
  * properties for fields on a specific entity type only.
  *
- * This hook is called once per field per added or edit entity. If the result
- * of the hook involves reading from the database, it is highly recommended to
+ * This hook is called once per field per added or edit entity. If the result of
+ * the hook involves reading from the database, it is highly recommended to
  * statically cache the information.
  *
  * @param $widget
@@ -2427,16 +2450,15 @@ function hook_field_create_instance($instance) {
 }
 
 /**
- * Forbid a field update from occurring.
+ * Forbid a field update to occur.
  *
- * Any module may forbid any update for any reason. For example, the
- * field's storage module might forbid an update if it would change
- * the storage schema while data for the field exists. A field type
- * module might forbid an update if it would change existing data's
- * semantics, or if there are external dependencies on field settings
- * that cannot be updated.
+ * Any module may forbid any update for any reason. For example, the field's
+ * storage module might forbid an update if it would change the storage schema
+ * while data for the field exists. A field type module might forbid an update
+ * if it would change existing data's semantics, or if there are external
+ * dependencies on field settings that cannot be updated.
  *
- * To forbid the update from occurring, throw a FieldUpdateForbiddenException.
+ * To forbid the update to occur, throw a FieldUpdateForbiddenException.
  *
  * @param $field
  *   The field as it will be post-update.
@@ -2549,11 +2571,11 @@ function hook_field_read_instance($instance) {
 /**
  * Acts when a field record is being purged.
  *
- * In field_purge_field(), after the field configuration has been
- * removed from the database, the field storage module has had a chance to
- * run its hook_field_storage_purge_field(), and the field info cache
- * has been cleared, this hook is invoked on all modules to allow them to
- * respond to the field being purged.
+ * In field_purge_field(), after the field configuration has been removed from
+ * the database, the field storage module has had a chance to run its
+ * hook_field_storage_purge_field(), and the field info cache has been cleared,
+ * this hook is invoked on all modules to allow them to respond to the field
+ * being purged.
  *
  * @param $field
  *   The field being purged.
@@ -2567,11 +2589,11 @@ function hook_field_purge_field($field) {
 /**
  * Acts when a field instance is being purged.
  *
- * In field_purge_instance(), after the field instance has been
- * removed from the database, the field storage module has had a chance to
- * run its hook_field_storage_purge_instance(), and the field info cache
- * has been cleared, this hook is invoked on all modules to allow them to
- * respond to the field instance being purged.
+ * In field_purge_instance(), after the field instance has been removed from the
+ * database, the field storage module has had a chance to run its
+ * hook_field_storage_purge_instance(), and the field info cache has been
+ * cleared, this hook is invoked on all modules to allow them to respond to the
+ * field instance being purged.
  *
  * @param $instance
  *   The instance being purged.
@@ -2585,8 +2607,8 @@ function hook_field_purge_instance($instance) {
 /**
  * Remove field storage information when a field record is purged.
  *
- * Called from field_purge_field() to allow the field storage module
- * to remove field information when a field is being purged.
+ * Called from field_purge_field() to allow the field storage module to remove
+ * field information when a field is being purged.
  *
  * @param $field
  *   The field being purged.
@@ -2601,9 +2623,8 @@ function hook_field_storage_purge_field($field) {
 /**
  * Remove field storage information when a field instance is purged.
  *
- * Called from field_purge_instance() to allow the field storage module
- * to remove field instance information when a field instance is being
- * purged.
+ * Called from field_purge_instance() to allow the field storage module to
+ * remove field instance information when a field instance is being purged.
  *
  * @param $instance
  *   The instance being purged.
@@ -2617,8 +2638,8 @@ function hook_field_storage_purge_field_instance($instance) {
 /**
  * Remove field storage information when field data is purged.
  *
- * Called from field_purge_data() to allow the field storage
- * module to delete field data information.
+ * Called from field_purge_data() to allow the field storage module to delete
+ * field data information.
  *
  * @param $entity_type
  *   The type of $entity; for example, 'node' or 'user'.
diff --git a/core/modules/field/field.attach.inc b/core/modules/field/field.attach.inc
index ff579c7..56ac45f 100644
--- a/core/modules/field/field.attach.inc
+++ b/core/modules/field/field.attach.inc
@@ -6,22 +6,24 @@
  */
 
 /**
- * Exception thrown by field_attach_validate() on field validation errors.
+ * Represents an exception thrown on field validation errors.
+ *
+ * This type of exception is thrown by field_attach_validate()
  */
 class FieldValidationException extends FieldException {
   var $errors;
 
  /**
-  * Constructor for FieldValidationException.
+  * Constructs a FieldValidationException object.
   *
   * @param $errors
-  *   An array of field validation errors, keyed by field name and
-  *   delta that contains two keys:
-  *   - 'error': A machine-readable error code string, prefixed by
-  *     the field module name. A field widget may use this code to decide
-  *     how to report the error.
-  *   - 'message': A human-readable error message such as to be
-  *     passed to form_error() for the appropriate form element.
+  *   An array of field validation errors, keyed by field name and delta that
+  *   contains two keys:
+  *   - error: A machine-readable error code string, prefixed by the field
+  *     module name. A field widget may use this code to decide how to report
+  *     the error.
+  *   - message: A human-readable error message such as to be pass to
+  *     form_error() for the appropriate form element.
   */
   function __construct($errors) {
     $this->errors = $errors;
@@ -32,7 +34,7 @@ class FieldValidationException extends FieldException {
 /**
  * @defgroup field_storage Field Storage API
  * @{
- * Implement a storage engine for Field API data.
+ * Implements a storage engine for Field API data.
  *
  * The Field Attach API uses the Field Storage API to perform all "database
  * access". Each Field Storage API hook function defines a primitive database
@@ -52,8 +54,7 @@ class FieldValidationException extends FieldException {
 /**
  * Argument for an update operation.
  *
- * This is used in hook_field_storage_write when updating an
- * existing entity.
+ * This is used in hook_field_storage_write when updating an existing entity.
  */
 const FIELD_STORAGE_UPDATE = 'update';
 
@@ -71,7 +72,7 @@ const FIELD_STORAGE_INSERT = 'insert';
 /**
  * @defgroup field_attach Field Attach API
  * @{
- * Operate on Field API data attached to Drupal entities.
+ * Operates on Field API data attached to Drupal entities.
  *
  * Field Attach API functions load, store, display, generate Field API
  * structures, and perform a variety of other functions for field data attached
@@ -82,18 +83,18 @@ const FIELD_STORAGE_INSERT = 'insert';
  * of the fieldable entity, such as 'node' or 'user', and $entity is the entity
  * itself.
  *
- * hook_entity_info() is the central place for entity types to define if and
- * how Field API should operate on their entity objects. Notably, the
- * 'fieldable' property needs to be set to TRUE.
+ * hook_entity_info() is the central place for entity types to define if and how
+ * Field API should operate on their entity objects. Notably, the 'fieldable'
+ * property needs to be set to TRUE.
  *
  * The Field Attach API uses the concept of bundles: the set of fields for a
  * given entity is defined on a per-bundle basis. The collection of bundles for
  * an entity type is defined its hook_entity_info() implementation. For
  * instance, node_entity_info() exposes each node type as its own bundle. This
  * means that the set of fields of a node is determined by the node type. The
- * Field API reads the bundle name for a given entity from a particular
- * property of the entity object, and hook_entity_info() defines which property
- * to use. For instance, node_entity_info() specifies:
+ * Field API reads the bundle name for a given entity from a particular property
+ * of the entity object, and hook_entity_info() defines which property to use.
+ * For instance, node_entity_info() specifies:
  * @code $info['entity keys']['bundle'] = 'type'@endcode
  * This indicates that for a particular node object, the bundle name can be
  * found in $node->type. This property can be omitted if the entity type only
@@ -110,16 +111,16 @@ const FIELD_STORAGE_INSERT = 'insert';
  *
  * field_attach_load(), field_attach_insert(), and field_attach_update() also
  * define pre-operation hooks, e.g. hook_field_attach_pre_load(). These hooks
- * run before the corresponding Field Storage API and Field Type API
- * operations. They allow modules to define additional storage locations (e.g.
+ * run before the corresponding Field Storage API and Field Type API operations.
+ * They allow modules to define additional storage locations (e.g.
  * denormalizing, mirroring) for field data on a per-field basis. They also
  * allow modules to take over field storage completely by instructing other
  * implementations of the same hook and the Field Storage API itself not to
  * operate on specified fields.
  *
  * The pre-operation hooks do not make the Field Storage API irrelevant. The
- * Field Storage API is essentially the "fallback mechanism" for any fields
- * that aren't being intercepted explicitly by pre-operation hooks.
+ * Field Storage API is essentially the "fallback mechanism" for any fields that
+ * aren't being intercepted explicitly by pre-operation hooks.
  *
  * @link field_language Field language API @endlink provides information about
  * the structure of field objects.
@@ -129,7 +130,7 @@ const FIELD_STORAGE_INSERT = 'insert';
  */
 
 /**
- * Invoke a field hook.
+ * Invokes a field hook.
  *
  * @param $op
  *   Possible operations include:
@@ -155,28 +156,30 @@ const FIELD_STORAGE_INSERT = 'insert';
  *   - Otherwise NULL.
  * @param $options
  *   An associative array of additional options, with the following keys:
- *  - 'field_name': The name of the field whose operation should be
- *    invoked. By default, the operation is invoked on all the fields
- *    in the entity's bundle. NOTE: This option is not compatible with
- *    the 'deleted' option; the 'field_id' option should be used
- *    instead.
- *  - 'field_id': The id of the field whose operation should be
- *    invoked. By default, the operation is invoked on all the fields
- *    in the entity's' bundles.
- *  - 'default': A boolean value, specifying which implementation of
- *    the operation should be invoked.
- *    - if FALSE (default), the field types implementation of the operation
- *      will be invoked (hook_field_[op])
- *    - If TRUE, the default field implementation of the field operation
- *      will be invoked (field_default_[op])
- *    Internal use only. Do not explicitely set to TRUE, but use
- *    _field_invoke_default() instead.
- *  - 'deleted': If TRUE, the function will operate on deleted fields
- *    as well as non-deleted fields. If unset or FALSE, only
- *    non-deleted fields are operated on.
- *  - 'langcode': A language code or an array of language codes keyed by field
- *    name. It will be used to narrow down to a single value the available
- *    languages to act on.
+ *   - field_name: The name of the field whose operation should be invoked. By
+ *     default, the operation is invoked on all the fields in the entity's
+ *     bundle. NOTE: This option is not compatible with the 'deleted' option;
+ *     the 'field_id' option should be used instead.
+ *   - field_id: The ID of the field whose operation should be invoked. By
+ *     default, the operation is invoked on all the fields in the entity's
+ *     bundles.
+ *   - default: A boolean value, specifying which implementation of the
+ *     operation should be invoked.
+ *     - If FALSE (default), the field types implementation of the operation
+ *       will be invoked (hook_field_[op])
+ *     - If TRUE, the default field implementation of the field operation will
+ *       be invoked (field_default_[op])
+ *     Internal use only. Do not explicitely set to TRUE, but use
+ *     _field_invoke_default() instead.
+ *   - deleted: If TRUE, the function will operate on deleted fields as well as
+ *     non-deleted fields. If unset or FALSE, only non-deleted fields are
+ *     operated on.
+ *   - langcode: A language code or an array of language codes keyed by field
+ *     name. It will be used to narrow down to a single value the available
+ *     languages to act on.
+ *
+ * @return
+ *   An array of the return values from the invoked hook implementations.
  */
 function _field_invoke($op, $entity_type, $entity, &$a = NULL, &$b = NULL, $options = array()) {
   // Merge default options.
@@ -231,7 +234,7 @@ function _field_invoke($op, $entity_type, $entity, &$a = NULL, &$b = NULL, $opti
 }
 
 /**
- * Invoke a field hook across fields on multiple entities.
+ * Invokes a field hook across fields on multiple entities.
  *
  * @param $op
  *   Possible operations include:
@@ -240,9 +243,9 @@ function _field_invoke($op, $entity_type, $entity, &$a = NULL, &$b = NULL, $opti
  *   For all other operations, use _field_invoke() / field_invoke_default()
  *   instead.
  * @param $entity_type
- *   The type of $entity; e.g. 'node' or 'user'.
+ *   The type of entities in $entities; e.g. 'node' or 'user'.
  * @param $entities
- *   An array of entities, keyed by entity id.
+ *   An array of entities, keyed by entity ID.
  * @param $a
  *   - The $age parameter in the 'load' operation.
  *   - Otherwise NULL.
@@ -250,30 +253,30 @@ function _field_invoke($op, $entity_type, $entity, &$a = NULL, &$b = NULL, $opti
  *   Currently always NULL.
  * @param $options
  *   An associative array of additional options, with the following keys:
- *  - 'field_name': The name of the field whose operation should be
- *    invoked. By default, the operation is invoked on all the fields
- *    in the entity's bundle. NOTE: This option is not compatible with
- *    the 'deleted' option; the 'field_id' option should be used instead.
- *  - 'field_id': The id of the field whose operation should be
- *    invoked. By default, the operation is invoked on all the fields
- *    in the entity's' bundles.
- *  - 'default': A boolean value, specifying which implementation of
- *    the operation should be invoked.
- *    - if FALSE (default), the field types implementation of the operation
- *      will be invoked (hook_field_[op])
- *    - If TRUE, the default field implementation of the field operation
- *      will be invoked (field_default_[op])
- *    Internal use only. Do not explicitely set to TRUE, but use
- *    _field_invoke_multiple_default() instead.
- *  - 'deleted': If TRUE, the function will operate on deleted fields
- *    as well as non-deleted fields. If unset or FALSE, only
- *    non-deleted fields are operated on.
- *  - 'langcode': A language code or an array of arrays of language codes keyed
- *    by entity id and field name. It will be used to narrow down to a single
- *    value the available language codes to act on.
+ *   - field_name: The name of the field whose operation should be invoked. By
+ *     default, the operation is invoked on all the fields in the entity's
+ *     bundle. NOTE: This option is not compatible with the 'deleted' option;
+ *     the 'field_id' option should be used instead.
+ *   - field_id: The ID of the field whose operation should be invoked. By
+ *     default, the operation is invoked on all the fields in the entity's
+ *     bundles.
+ *   - default: A boolean value, specifying which implementation of the
+ *     operation should be invoked.
+ *     - if FALSE (default), the field types implementation of the operation
+ *       will be invoked (hook_field_[op])
+ *     - If TRUE, the default field implementation of the field operation will
+ *       be invoked (field_default_[op])
+ *     Internal use only. Do not explicitely set to TRUE, but use
+ *     _field_invoke_multiple_default() instead.
+ *   - deleted: If TRUE, the function will operate on deleted fields as well as
+ *     non-deleted fields. If unset or FALSE, only non-deleted fields are
+ *     operated on.
+ *   - langcode: A language code or an array of arrays of language codes keyed
+ *     by entity ID and field name. It will be used to narrow down to a single
+ *     value the available languages to act on.
  *
  * @return
- *   An array of returned values keyed by entity id.
+ *   An array of returned values keyed by entity ID.
  */
 function _field_invoke_multiple($op, $entity_type, $entities, &$a = NULL, &$b = NULL, $options = array()) {
   // Merge default options.
@@ -294,7 +297,7 @@ function _field_invoke_multiple($op, $entity_type, $entities, &$a = NULL, &$b =
   // Go through the entities and collect the fields on which the hook should be
   // invoked.
   //
-  // We group fields by id, not by name, because this function can operate on
+  // We group fields by ID, not by name, because this function can operate on
   // deleted fields which may have non-unique names. However, entities can only
   // contain data for a single field for each name, even if that field
   // is deleted, so we reference field data via the
@@ -373,13 +376,59 @@ function _field_invoke_multiple($op, $entity_type, $entities, &$a = NULL, &$b =
 }
 
 /**
- * Invoke field.module's version of a field hook.
+ * Invokes field.module's version of a field hook.
  *
- * This function invokes the field_default_[op]() function.
- * Use _field_invoke() to invoke the field type implementation,
- * hook_field_[op]().
+ * This function invokes the field_default_[op]() function. Use _field_invoke()
+ * to invoke the field type implementation, hook_field_[op]().
  *
- * @see _field_invoke()
+ * @param $op
+ *   Possible operations include:
+ *   - form
+ *   - validate
+ *   - presave
+ *   - insert
+ *   - update
+ *   - delete
+ *   - delete revision
+ *   - view
+ *   - prepare translation
+ * @param $entity_type
+ *   The type of $entity; e.g. 'node' or 'user'.
+ * @param $entity
+ *   The fully formed $entity_type entity.
+ * @param $a
+ *   - The $form in the 'form' operation.
+ *   - The value of $view_mode in the 'view' operation.
+ *   - Otherwise NULL.
+ * @param $b
+ *   - The $form_state in the 'submit' operation.
+ *   - Otherwise NULL.
+ * @param $options
+ *   An associative array of additional options, with the following keys:
+ *   - field_name: The name of the field whose operation should be invoked. By
+ *     default, the operation is invoked on all the fields in the entity's
+ *     bundle. NOTE: This option is not compatible with the 'deleted' option;
+ *     the 'field_id' option should be used instead.
+ *   - field_id: The ID of the field whose operation should be invoked. By
+ *     default, the operation is invoked on all the fields in the entity's
+ *     bundles.
+ *   - default: A boolean value, specifying which implementation of the
+ *     operation should be invoked.
+ *     - If FALSE (default), the field types implementation of the operation
+ *       will be invoked (hook_field_[op])
+ *     - If TRUE, the default field implementation of the field operation will
+ *       be invoked (field_default_[op])
+ *     Internal use only. Do not explicitely set to TRUE, but use
+ *     _field_invoke_default() instead.
+ *   - deleted: If TRUE, the function will operate on deleted fields as well as
+ *     non-deleted fields. If unset or FALSE, only non-deleted fields are
+ *     operated on.
+ *   - language: A language code or an array of language codes keyed by field
+ *     name. It will be used to narrow down to a single value the available
+ *     languages to act on.
+ *
+ * @return
+ *   An array of the return values from the default hook implementation.
  */
 function _field_invoke_default($op, $entity_type, $entity, &$a = NULL, &$b = NULL, $options = array()) {
   $options['default'] = TRUE;
@@ -393,6 +442,48 @@ function _field_invoke_default($op, $entity_type, $entity, &$a = NULL, &$b = NUL
  * Use _field_invoke_multiple() to invoke the field type implementation,
  * hook_field_[op]().
  *
+ * @param $op
+ *   Possible operations include:
+ *   - load
+ *   - prepare_view
+ *   For all other operations, use _field_invoke() / field_invoke_default()
+ *   instead.
+ * @param $entity_type
+ *   The type of entities in $entities; e.g. 'node' or 'user'.
+ * @param $entities
+ *   An array of entities, keyed by entity ID.
+ * @param $a
+ *   - The $age parameter in the 'load' operation.
+ *   - Otherwise NULL.
+ * @param $b
+ *   Currently always NULL.
+ * @param $options
+ *   An associative array of additional options, with the following keys:
+ *   - field_name: The name of the field whose operation should be invoked. By
+ *     default, the operation is invoked on all the fields in the entity's
+ *     bundle. NOTE: This option is not compatible with the 'deleted' option;
+ *     the 'field_id' option should be used instead.
+ *   - field_id: The ID of the field whose operation should be invoked. By
+ *     default, the operation is invoked on all the fields in the entity's
+ *     bundles.
+ *   - default': A boolean value, specifying which implementation of the
+ *     operation should be invoked.
+ *     - if FALSE (default), the field types implementation of the operation
+ *       will be invoked (hook_field_[op])
+ *     - If TRUE, the default field implementation of the field operation will
+ *       be invoked (field_default_[op])
+ *     Internal use only. Do not explicitely set to TRUE, but use
+ *     _field_invoke_multiple_default() instead.
+ *   - deleted: If TRUE, the function will operate on deleted fields as well as
+ *     non-deleted fields. If unset or FALSE, only non-deleted fields are
+ *     operated on.
+ *   - language: A language code or an array of arrays of language codes keyed
+ *     by entity ID and field name. It will be used to narrow down to a single
+ *     value the available languages to act on.
+ *
+ * @return
+ *   An array of returned values keyed by entity ID.
+ *
  * @see _field_invoke_multiple()
  */
 function _field_invoke_multiple_default($op, $entity_type, $entities, &$a = NULL, &$b = NULL, $options = array()) {
@@ -401,7 +492,9 @@ function _field_invoke_multiple_default($op, $entity_type, $entities, &$a = NULL
 }
 
 /**
- * Helper for _field_invoke(): retrieves a list of instances to operate on.
+ * Retrieves a list of instances to operate on.
+ *
+ * Helper for _field_invoke().
  *
  * @param $entity_type
  *   The entity type.
@@ -409,7 +502,7 @@ function _field_invoke_multiple_default($op, $entity_type, $entities, &$a = NULL
  *   The bundle name.
  * @param $options
  *   An associative array of options, as provided to _field_invoke(). Only the
- *   following keys are considered :
+ *   following keys are considered:
  *   - deleted
  *   - field_name
  *   - field_id
@@ -454,7 +547,7 @@ function _field_invoke_get_instances($entity_type, $bundle, $options) {
 }
 
 /**
- * Add form elements for all fields for an entity to a form structure.
+ * Adds form elements for all fields for an entity to a form structure.
  *
  * The form elements for the entity's fields are added by reference as direct
  * children in the $form parameter. This parameter can be a full form structure
@@ -542,19 +635,19 @@ function _field_invoke_get_instances($entity_type, $bundle, $options) {
  * @param $entity_type
  *   The type of $entity; e.g. 'node' or 'user'.
  * @param $entity
- *   The entity for which to load form elements, used to initialize
- *   default form values.
+ *   The entity for which to load form elements, used to initialize default form
+ *   values.
  * @param $form
  *   The form structure to fill in. This can be a full form structure, or a
  *   sub-element of a larger form. The #parents property can be set to control
- *   the location of submitted field values within $form_state['values']. If
- *   not specified, $form['#parents'] is set to an empty array, placing field
- *   values at the top-level of $form_state['values'].
+ *   the location of submitted field values within $form_state['values']. If not
+ *   specified, $form['#parents'] is set to an empty array, placing field values
+ *   at the top-level of $form_state['values'].
  * @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, if no language
- *   is provided the default site language will be used.
+ *   The language the field values are going to be entered, if no language is
+ *   provided the default site language will be used.
  *
  * @see field_form_get_state()
  * @see field_form_set_state()
@@ -592,26 +685,25 @@ function field_attach_form($entity_type, $entity, &$form, &$form_state, $langcod
  * entity type module.
  *
  * @param $entity_type
- *   The type of $entity; e.g., 'node' or 'user'.
+ *   The type of entities in $entities; e.g., 'node' or 'user'.
  * @param $entities
- *   An array of entities for which to load fields, keyed by entity ID.
- *   Each entity needs to have its 'bundle', 'id' and (if applicable)
- *   'revision' keys filled in. The function adds the loaded field data
- *   directly in the entity objects of the $entities array.
+ *   An array of entities for which to load fields, keyed by entity ID. Each
+ *   entity needs to have its 'bundle', 'id' and (if applicable) 'revision' keys
+ *   filled in. The function adds the loaded field data directly in the entity
+ *   objects of the $entities array.
  * @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. Defaults to FIELD_LOAD_CURRENT; use
- *   field_attach_load_revision() instead of passing FIELD_LOAD_REVISION.
+ *   FIELD_LOAD_CURRENT to load the most recent revision for all fields, or
+ *   FIELD_LOAD_REVISION to load the version indicated by each entity. Defaults
+ *   to FIELD_LOAD_CURRENT; use field_attach_load_revision() instead of passing
+ *   FIELD_LOAD_REVISION.
  * @param $options
  *   An associative array of additional options, with the following keys:
- *   - 'field_id': The field ID that should be loaded, instead of
- *     loading all fields, for each entity. Note that returned entities
- *     may contain data for other fields, for example if they are read
- *     from a cache.
- *   - 'deleted': If TRUE, the function will operate on deleted fields
- *     as well as non-deleted fields. If unset or FALSE, only
- *     non-deleted fields are operated on.
+ *   - field_id: The field ID that should be loaded, instead of loading all
+ *     fields, for each entity. Note that returned entities may contain data for
+ *     other fields, for example if they are read from a cache.
+ *   - deleted: If TRUE, the function will operate on deleted fields as well as
+ *     non-deleted fields. If unset or FALSE, only non-deleted fields are
+ *     operated on.
  */
 function field_attach_load($entity_type, $entities, $age = FIELD_LOAD_CURRENT, $options = array()) {
   $field_info = field_info_field_by_ids();
@@ -729,7 +821,7 @@ function field_attach_load($entity_type, $entities, $age = FIELD_LOAD_CURRENT, $
 }
 
 /**
- * Load all fields for previous versions of a group of entities.
+ * Loads all fields for previous versions of a group of entities.
  *
  * Loading different versions of the same entities is not supported, and should
  * be done by separate calls to the function.
@@ -739,12 +831,12 @@ function field_attach_load($entity_type, $entities, $age = FIELD_LOAD_CURRENT, $
  * called by the entity type module.
  *
  * @param $entity_type
- *   The type of $entity; e.g. 'node' or 'user'.
+ *   The type of entities in $entities; e.g. 'node' or 'user'.
  * @param $entities
  *   An array of entities for which to load fields, keyed by entity ID. Each
- *   entity needs to have its 'bundle', 'id' and (if applicable) 'revision'
- *   keys filled. The function adds the loaded field data directly in the
- *   entity objects of the $entities array.
+ *   entity needs to have its 'bundle', 'id' and (if applicable) 'revision' keys
+ *   filled. The function adds the loaded field data directly in the entity
+ *   objects of the $entities array.
  * @param $options
  *   An associative array of additional options. See field_attach_load() for
  *   details.
@@ -754,12 +846,11 @@ function field_attach_load_revision($entity_type, $entities, $options = array())
 }
 
 /**
- * Perform field validation against the field data in an entity.
+ * Performs field validation against the field data in an entity.
  *
- * This function does not perform field widget validation on form
- * submissions. It is intended to be called during API save
- * operations. Use field_attach_form_validate() to validate form
- * submissions.
+ * This function does not perform field widget validation on form submissions.
+ * It is intended to be called during API save operations. Use
+ * field_attach_form_validate() to validate form submissions.
  *
  * @param $entity_type
  *   The type of $entity; e.g. 'node' or 'user'.
@@ -790,21 +881,21 @@ function field_attach_validate($entity_type, $entity) {
 }
 
 /**
- * Perform field validation against form-submitted field values.
+ * Performs field validation against form-submitted field values.
  *
- * There are two levels of validation for fields in forms: widget
- * validation, and field validation.
- * - Widget validation steps are specific to a given widget's own form
- *   structure and UI metaphors. They are executed through FAPI's
- *   #element_validate property during normal form validation.
+ * There are two levels of validation for fields in forms: widget validation and
+ * and field validation.
+ * - Widget validation steps are specific to a given widget's own form structure
+ *   and UI metaphors. They are executed through FAPI's #element_validate
+ *   property during normal form validation.
  * - Field validation steps are common to a given field type, independently of
  *   the specific widget being used in a given form. They are defined in the
  *   field type's implementation of hook_field_validate().
  *
- * This function performs field validation in the context of a form
- * submission. It converts field validation errors into form errors
- * on the correct form elements. Fieldable entity types should call
- * this function during their own form validation function.
+ * This function performs field validation in the context of a form submission.
+ * It converts field validation errors into form errors on the correct form
+ * elements. Fieldable entity types should call this function during their own
+ * form validation function.
  *
  * @param $entity_type
  *   The type of $entity; e.g. 'node' or 'user'.
@@ -841,10 +932,10 @@ function field_attach_form_validate($entity_type, $entity, $form, &$form_state)
 }
 
 /**
- * Perform necessary operations on field data submitted by a form.
+ * Performs necessary operations on field data submitted by a form.
  *
- * Currently, this accounts for drag-and-drop reordering of
- * field values, and filtering of empty values.
+ * Currently, this accounts for drag-and-drop reordering of field values, and
+ * filtering of empty values.
  *
  * @param $entity_type
  *   The type of $entity; e.g. 'node' or 'user'.
@@ -873,10 +964,10 @@ function field_attach_submit($entity_type, $entity, $form, &$form_state) {
 }
 
 /**
- * Perform necessary operations just before fields data get saved.
+ * Performs necessary operations just before fields data get saved.
  *
- * We take no specific action here, we just give other
- * modules the opportunity to act.
+ * We take no specific action here, we just give other modules the opportunity
+ * to act.
  *
  * @param $entity_type
  *   The type of $entity; e.g. 'node' or 'user'.
@@ -891,20 +982,19 @@ function field_attach_presave($entity_type, $entity) {
 }
 
 /**
- * Save field data for a new entity.
+ * Saves field data for a new entity.
  *
- * The passed-in entity must already contain its id and (if applicable)
- * revision id attributes.
- * Default values (if any) will be saved for fields not present in the
- * $entity.
+ * The passed-in entity must already contain its id and (if applicable) revision
+ * ID attributes. Default values (if any) will be saved for fields not present
+ * in the entity.
+ *
+ * Default values (if any) will be added to the $entity parameter for fields it
+ * leaves unspecified.
  *
  * @param $entity_type
  *   The type of $entity; e.g. 'node' or 'user'.
  * @param $entity
  *   The entity with fields to save.
- * @return
- *   Default values (if any) will be added to the $entity parameter for fields
- *   it leaves unspecified.
  */
 function field_attach_insert($entity_type, $entity) {
   _field_invoke_default('insert', $entity_type, $entity);
@@ -947,7 +1037,7 @@ function field_attach_insert($entity_type, $entity) {
 }
 
 /**
- * Save field data for an existing entity.
+ * Saves field data for an existing entity.
  *
  * @param $entity_type
  *   The type of $entity; e.g. 'node' or 'user'.
@@ -1001,8 +1091,8 @@ function field_attach_update($entity_type, $entity) {
 }
 
 /**
- * Delete field data for an existing entity. This deletes all
- * revisions of field data for the entity.
+ * Deletes field data for an existing entity. This deletes all revisions of
+ * field data for the entity.
  *
  * @param $entity_type
  *   The type of $entity; e.g. 'node' or 'user'.
@@ -1038,8 +1128,8 @@ function field_attach_delete($entity_type, $entity) {
 }
 
 /**
- * Delete field data for a single revision of an existing entity. The
- * passed entity must have a revision id attribute.
+ * Delete field data for a single revision of an existing entity. The passed
+ * entity must have a revision ID attribute.
  *
  * @param $entity_type
  *   The type of $entity; e.g. 'node' or 'user'.
@@ -1070,24 +1160,23 @@ function field_attach_delete_revision($entity_type, $entity) {
 }
 
 /**
- * Prepare field data prior to display.
- *
- * This function lets field types and formatters load additional data
- * needed for display that is not automatically loaded during
- * field_attach_load(). It accepts an array of entities to allow query
- * optimisation when displaying lists of entities.
- *
- * field_attach_prepare_view() and field_attach_view() are two halves
- * of the same operation. It is safe to call
- * field_attach_prepare_view() multiple times on the same entity
- * before calling field_attach_view() on it, but calling any Field
- * API operation on an entity between passing that entity to these two
+ * Prepares field data prior to display.
+ *
+ * This function lets field types and formatters load additional data needed for
+ * display that is not automatically loaded during field_attach_load(). It
+ * accepts an array of entities to allow query optimization when displaying
+ * lists of entities.
+ *
+ * field_attach_prepare_view() and field_attach_view() are two halves of the
+ * same operation. It is safe to call field_attach_prepare_view() multiple times
+ * on the same entity before calling field_attach_view() on it, but calling any
+ * Field API operation on an entity between passing that entity to these two
  * functions may yield incorrect results.
  *
  * @param $entity_type
- *   The type of $entities; e.g. 'node' or 'user'.
+ *   The type of entities in $entities; e.g. 'node' or 'user'.
  * @param $entities
- *   An array of entities, keyed by entity id.
+ *   An array of entities, keyed by entity ID.
  * @param $view_mode
  *   View mode, e.g. 'full', 'teaser'...
  * @param $langcode
@@ -1128,13 +1217,12 @@ function field_attach_prepare_view($entity_type, $entities, $view_mode, $langcod
  * Returns a renderable array for the fields on an entity.
  *
  * Each field is displayed according to the display options specified in the
- * $instance definition for the given $view_mode.
+ * instance definition for the given view mode.
  *
- * field_attach_prepare_view() and field_attach_view() are two halves
- * of the same operation. It is safe to call
- * field_attach_prepare_view() multiple times on the same entity
- * before calling field_attach_view() on it, but calling any Field
- * API operation on an entity between passing that entity to these two
+ * field_attach_prepare_view() and field_attach_view() are two halves of the
+ * same operation. It is safe to call field_attach_prepare_view() multiple times
+ * on the same entity before calling field_attach_view() on it, but calling any
+ * Field API operation on an entity between passing that entity to these two
  * functions may yield incorrect results.
  *
  * Sample structure:
@@ -1205,7 +1293,7 @@ function field_attach_view($entity_type, $entity, $view_mode, $langcode = NULL)
 }
 
 /**
- * Populate the template variables with the field values available for rendering.
+ * Populates the template variables with the available field values.
  *
  * The $variables array will be populated with all the field instance values
  * associated with the given entity type, keyed by field name; in case of
@@ -1219,8 +1307,8 @@ function field_attach_view($entity_type, $entity, $view_mode, $langcode = NULL)
  * @param $element
  *   The structured array containing the values ready for rendering.
  * @param $variables
- *   The variables array is passed by reference and will be populated with field
- *   values.
+ *   The $variables array is passed by reference and will be populated with 
+ *   field values.
  */
 function field_attach_preprocess($entity_type, $entity, $element, &$variables) {
   list(, , $bundle) = entity_extract_ids($entity_type, $entity);
@@ -1245,7 +1333,7 @@ function field_attach_preprocess($entity_type, $entity, $element, &$variables) {
 /**
  * Prepares an entity for translation.
  *
- * This function is used to fill-in the form default values for Field API fields
+ * This function is used to fill in the form default values for Field API fields
  * while performing entity translation. By default it copies all the source
  * values in the given source language to the new entity and assigns them the
  * target language.
@@ -1259,11 +1347,11 @@ function field_attach_preprocess($entity_type, $entity, $element, &$variables) {
  * @param $entity
  *   The entity to be prepared for translation.
  * @param $langcode
- *   The language the entity has to be translated in.
+ *   The language the entity has to be translated to.
  * @param $source_entity
  *   The source entity holding the field values to be translated.
  * @param $source_langcode
- *   The source language from which translate.
+ *   The source language from which to translate.
  */
 function field_attach_prepare_translation($entity_type, $entity, $langcode, $source_entity, $source_langcode) {
   $options = array('langcode' => $langcode);
@@ -1282,7 +1370,7 @@ function field_attach_prepare_translation($entity_type, $entity, $langcode, $sou
 }
 
 /**
- * Notify field.module that a new bundle was created.
+ * Notifies field.module that a new bundle was created.
  *
  * The default SQL-based storage doesn't need to do anything about it, but
  * others might.
@@ -1301,7 +1389,7 @@ function field_attach_create_bundle($entity_type, $bundle) {
 }
 
 /**
- * Notify field.module that a bundle was renamed.
+ * Notifies field.module that a bundle was renamed.
  *
  * @param $entity_type
  *   The entity type to which the bundle is bound.
@@ -1331,12 +1419,12 @@ function field_attach_rename_bundle($entity_type, $bundle_old, $bundle_new) {
 }
 
 /**
- * Notify field.module the a bundle was deleted.
+ * Notifies field.module the 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
- * and deleted, leaving the garbage collection for a separate process, because
- * it is not always possible to delete this much data in a single page request
+ * themselves. This function actually just marks the data and field instances as
+ * deleted, leaving the garbage collection for a separate process, because it is
+ * not always possible to delete this much data in a single page request
  * (particularly since for some field types, the deletion is more than just a
  * simple DELETE query).
  *
diff --git a/core/modules/field/field.crud.inc b/core/modules/field/field.crud.inc
index f9c96c9..2128bcd 100644
--- a/core/modules/field/field.crud.inc
+++ b/core/modules/field/field.crud.inc
@@ -8,13 +8,12 @@
 /**
  * @defgroup field_crud Field CRUD API
  * @{
- * Create, update, and delete Field API fields, bundles, and instances.
+ * Creates, updates, and deletes Field API fields, bundles, and instances.
  *
- * Modules use this API, often in hook_install(), to create custom
- * data structures. UI modules will use it to create a user interface.
+ * Modules use this API, often in hook_install(), to create custom data
+ * structures. UI modules will use it to create a user interface.
  *
- * The Field CRUD API uses
- * @link field Field API data structures @endlink.
+ * The Field CRUD API uses @link field Field API data structures @endlink.
  *
  * See @link field Field API @endlink for information about the other parts of
  * the Field API.
@@ -29,25 +28,25 @@
  * @param $field
  *   A field definition array. The field_name and type properties are required.
  *   Other properties, if omitted, will be given the following default values:
- *   - cardinality: 1
- *   - locked: FALSE
- *   - indexes: the field-type indexes, specified by the field type's
- *     hook_field_schema(). The indexes specified in $field are added
- *     to those default indexes. It is possible to override the
- *     definition of a field-type index by providing an index with the
- *     same name, or to remove it by redefining it as an empty array
- *     of columns. Overriding field-type indexes should be done
- *     carefully, for it might seriously affect the site's performance.
- *   - settings: each omitted setting is given the default value defined in
+ *   - cardinality: 1.
+ *   - locked: FALSE.
+ *   - indexes: The field-type indexes, specified by the field type's
+ *     hook_field_schema(). The indexes specified in $field are added to those
+ *     default indexes. It is possible to override the definition of a
+ *     field-type index by providing an index with the same name, or to remove
+ *     it by redefining it as an empty array of columns. Overriding field-type
+ *     indexes should be done carefully, for it might seriously affect the
+ *     site's performance.
+ *   - settings: Each omitted setting is given the default value defined in
  *     hook_field_info().
  *   - storage:
- *     - type: the storage backend specified in the 'field_storage_default'
+ *     - type: The storage backend specified in the 'field_storage_default'
  *       system variable.
- *     - settings: each omitted setting is given the default value specified in
+ *     - settings: Each omitted setting is given the default value specified in
  *       hook_field_storage_info().
  *
  * @return
- *   The $field array with the id property filled in.
+ *   The $field array with the ID property filled in.
  *
  * @throws FieldException
  *
@@ -200,21 +199,21 @@ function field_create_field($field) {
 /**
  * Updates a field.
  *
- * Any module may forbid any update for any reason. For example, the
- * field's storage module might forbid an update if it would change
- * the storage schema while data for the field exists. A field type
- * module might forbid an update if it would change existing data's
- * semantics, or if there are external dependencies on field settings
- * that cannot be updated.
+ * Any module may forbid any update for any reason. For example, the field's
+ * storage module might forbid an update if it would change the storage schema
+ * while data for the field exists. A field type module might forbid an update
+ * update if it would change existing data's semantics, or if there are external
+ * dependencies on field settings that cannot be updated.
+ *
+ * Throws a FieldException if the update cannot be performed.
  *
  * @param $field
- *   A field structure. $field['field_name'] must provided; it
- *   identifies the field that will be updated to match this
- *   structure. Any other properties of the field that are not
- *   specified in $field will be left unchanged, so it is not
- *   necessary to pass in a fully populated $field structure.
- * @return
- *   Throws a FieldException if the update cannot be performed.
+ *   A field structure. $field['field_name'] must provided; it identifies the
+ *   field that will be updated to match this structure. Any other properties of
+ *   the field that are not specified in $field will be left unchanged, so it is
+ *   not necessary to pass in a fully populated $field structure.
+ *
+ * @throws FieldException
  * @see field_create_field()
  */
 function field_update_field($field) {
@@ -297,16 +296,16 @@ function field_update_field($field) {
  *
  * Generally, you should use the field_info_field() instead.
  *
- * This function will not return deleted fields. Use
- * field_read_fields() instead for this purpose.
+ * This function will not return deleted fields. Use field_read_fields() instead
+ * for this purpose.
  *
  * @param $field_name
  *   The field name to read.
  * @param array $include_additional
- *   The default behavior of this function is to not return a field that
- *   is inactive. Setting
- *   $include_additional['include_inactive'] to TRUE will override this
- *   behavior.
+ *   The default behavior of this function is to not return a field that is
+ *   inactive. Setting $include_additional['include_inactive'] to TRUE will
+ *   override this behavior.
+ *
  * @return
  *   A field definition array, or FALSE.
  */
@@ -321,15 +320,15 @@ function field_read_field($field_name, $include_additional = array()) {
  * @param array $params
  *   An array of conditions to match against.
  * @param array $include_additional
- *   The default behavior of this function is to not return fields that
- *   are inactive or have been deleted. Setting
+ *   The default behavior of this function is to not return fields that are
+ *   inactive or have been deleted. Setting
  *   $include_additional['include_inactive'] or
- *   $include_additional['include_deleted'] to TRUE will override this
- *   behavior.
+ *   $include_additional['include_deleted'] to TRUE will override this behavior.
+ *
  * @return
  *   An array of fields matching $params. If
- *   $include_additional['include_deleted'] is TRUE, the array is keyed
- *   by field id, otherwise it is keyed by field name.
+ *   $include_additional['include_deleted'] is TRUE, the array is keyed by
+ *   field ID, otherwise it is keyed by field name.
  */
 function field_read_fields($params = array(), $include_additional = array()) {
   $query = db_select('field_config', 'fc', array('fetch' => PDO::FETCH_ASSOC));
@@ -420,32 +419,31 @@ function field_delete_field($field_name) {
  * Creates an instance of a field, binding it to a bundle.
  *
  * @param $instance
- *   A field instance definition array. The field_name, entity_type and
- *   bundle properties are required. Other properties, if omitted,
- *   will be given the following default values:
- *   - label: the field name
- *   - description: empty string
- *   - required: FALSE
- *   - default_value_function: empty string
- *   - settings: each omitted setting is given the default value specified in
+ *   A field instance definition array. The field_name, entity_type and bundle
+ *   properties are required. Other properties, if omitted, will be given the
+ *   following default values:
+ *   - label: The field name.
+ *   - description: An empty string.
+ *   - required: FALSE.
+ *   - default_value_function: An empty string.
+ *   - settings: Each omitted setting is given the default value specified in
  *     hook_field_info().
  *   - widget:
- *     - type: the default widget specified in hook_field_info().
- *     - settings: each omitted setting is given the default value specified in
+ *     - type: The default widget specified in hook_field_info().
+ *     - settings: Each omitted setting is given the default value specified in
  *       hook_field_widget_info().
- *   - display:
- *     Settings for the 'default' view mode will be added if not present, and
- *     each view mode in the definition will be completed with the following
- *     default values:
- *     - label: 'above'
- *     - type: the default formatter specified in hook_field_info().
- *     - settings: each omitted setting is given the default value specified in
+ *   - display: Settings for the 'default' view mode will be added if not
+ *     present, and each view mode in the definition will be completed with the
+ *     following default values:
+ *     - label: "above".
+ *     - type: The default formatter specified in hook_field_info().
+ *     - settings: Each omitted setting is given the default value specified in
  *       hook_field_formatter_info().
  *     View modes not present in the definition are left empty, and the field
  *     will not be displayed in this mode.
  *
  * @return
- *   The $instance array with the id property filled in.
+ *   The $instance array with the ID property filled in.
  *
  * @throws FieldException
  *
@@ -505,12 +503,12 @@ function field_create_instance($instance) {
  * Updates an instance of a field.
  *
  * @param $instance
- *   An associative array representing an instance structure. The required
- *   keys and values are:
+ *   An associative array representing an instance structure. The required keys
+ *   and values are:
  *   - entity_type: The type of the entity the field is attached to.
  *   - bundle: The bundle this field belongs to.
  *   - field_name: The name of an existing field.
- *   Read-only_id properties are assigned automatically. Any other
+ *   Read-only ID properties are assigned automatically. Any other properties
  *   properties specified in $instance overwrite the existing values for
  *   the instance.
  *
@@ -638,9 +636,9 @@ function _field_write_instance($instance, $update = FALSE) {
 /**
  * Reads a single instance record from the database.
  *
- * Generally, you should use field_info_instance() instead, as it
- * provides caching and allows other modules the opportunity to
- * append additional formatters, widgets, and other information.
+ * Generally, you should use field_info_instance() instead, as it provides
+ * caching and allows other modules the opportunity to append additional
+ * formatters, widgets, and other information.
  *
  * @param $entity_type
  *   The type of entity to which the field is bound.
@@ -649,11 +647,11 @@ function _field_write_instance($instance, $update = FALSE) {
  * @param $bundle
  *   The bundle to which the field is bound.
  * @param array $include_additional
- *   The default behavior of this function is to not return an instance that
- *   has been deleted, or whose field is inactive. Setting
+ *   The default behavior of this function is to not return an instance that has
+ *   been deleted, or whose field is inactive. Setting
  *   $include_additional['include_inactive'] or
- *   $include_additional['include_deleted'] to TRUE will override this
- *   behavior.
+ *   $include_additional['include_deleted'] to TRUE will override this behavior.
+ *
  * @return
  *   An instance structure, or FALSE.
  */
@@ -666,15 +664,15 @@ function field_read_instance($entity_type, $field_name, $bundle, $include_additi
  * Reads in field instances that match an array of conditions.
  *
  * @param $param
- *   An array of properties to use in selecting a field
- *   instance. Valid keys include any column of the
- *   field_config_instance table. If NULL, all instances will be returned.
+ *   An array of properties to use in selecting a field instance. Valid keys
+ *   include any column of the field_config_instance table. If NULL, all
+ *   instances will be returned.
  * @param $include_additional
- *   The default behavior of this function is to not return field
- *   instances that have been marked deleted, or whose field is inactive.
- *   Setting $include_additional['include_inactive'] or
- *   $include_additional['include_deleted'] to TRUE will override this
- *   behavior.
+ *   The default behavior of this function is to not return field instances that
+ *   have been marked deleted, or whose field is inactive. Setting
+ *   $include_additional['include_inactive'] or
+ *   $include_additional['include_deleted'] to TRUE will override this behavior.
+ *
  * @return
  *   An array of instances matching the arguments.
  */
@@ -765,7 +763,7 @@ function field_delete_instance($instance, $field_cleanup = TRUE) {
 /**
  * @defgroup field_purge Field API bulk data deletion
  * @{
- * Clean up after Field API bulk deletion operations.
+ * Cleans up after Field API bulk deletion operations.
  *
  * Field API provides functions for deleting data attached to individual
  * entities as well as deleting entire fields or field instances in a single
@@ -774,20 +772,19 @@ function field_delete_instance($instance, $field_cleanup = TRUE) {
  * Deleting field data items for an entity with field_attach_delete() involves
  * three separate operations:
  * - Invoking the Field Type API hook_field_delete() for each field on the
- * entity. The hook for each field type receives the entity and the specific
- * field being deleted. A file field module might use this hook to delete
- * uploaded files from the filesystem.
- * - Invoking the Field Storage API hook_field_storage_delete() to remove
- * data from the primary field storage. The hook implementation receives the
- * entity being deleted and deletes data for all of the entity's bundle's
- * fields.
+ *   entity. The hook for each field type receives the entity and the specific
+ *   field being deleted. A file field module might use this hook to delete
+ *   uploaded files from the filesystem.
+ * - Invoking the Field Storage API hook_field_storage_delete() to remove data
+ *   from the primary field storage. The hook implementation receives the entity
+ *   being deleted and deletes data for all of the entity's bundle's fields.
  * - Invoking the global Field Attach API hook_field_attach_delete() for all
- * modules that implement it. Each hook implementation receives the entity
- * being deleted and can operate on whichever subset of the entity's bundle's
- * fields it chooses to.
+ *   modules that implement it. Each hook implementation receives the entity
+ *   being deleted and can operate on whichever subset of the entity's bundle's
+ *   fields it chooses to.
  *
- * These hooks are invoked immediately when field_attach_delete() is
- * called. Similar operations are performed for field_attach_delete_revision().
+ * These hooks are invoked immediately when field_attach_delete() is called.
+ * Similar operations are performed for field_attach_delete_revision().
  *
  * When a field, bundle, or field instance is deleted, it is not practical to
  * invoke these hooks immediately on every affected entity in a single page
@@ -795,8 +792,8 @@ function field_delete_instance($instance, $field_cleanup = TRUE) {
  * appropriate field data items, instances, and/or fields are marked as deleted
  * so that subsequent load or query operations will not return them. Later, a
  * separate process cleans up, or "purges", the marked-as-deleted data by going
- * through the three-step process described above and, finally, removing
- * deleted field and instance records.
+ * through the three-step process described above and, finally, removing deleted
+ * field and instance records.
  *
  * Purging field data is made somewhat tricky by the fact that, while
  * field_attach_delete() has a complete entity to pass to the various deletion
@@ -808,12 +805,12 @@ function field_delete_instance($instance, $field_cleanup = TRUE) {
  *
  * Field API resolves this problem by using "pseudo-entities" during purge
  * operations. A pseudo-entity contains only the information from the original
- * entity that Field API knows about: entity type, id, revision id, and
- * bundle. It also contains the field data for whichever field instance is
- * currently being purged. For example, suppose that the node type 'story' used
- * to contain a field called 'subtitle' but the field was deleted. If node 37
- * was a story with a subtitle, the pseudo-entity passed to the purge hooks
- * would look something like this:
+ * entity that Field API knows about: entity type, ID, revision ID, and bundle.
+ * It also contains the field data for whichever field instance is currently
+ * being purged. For example, suppose that the node type 'story' used to contain
+ * a field called 'subtitle' but the field was deleted. If node 37 was a story
+ * with a subtitle, the pseudo-entity passed to the purge hooks would look
+ * something like this:
  *
  * @code
  *   $entity = stdClass Object(
@@ -890,8 +887,8 @@ function field_purge_batch($batch_size) {
 /**
  * Purges the field data for a single field on a single pseudo-entity.
  *
- * This is basically the same as field_attach_delete() except it only applies
- * to a single field. The entity itself is not being deleted, and it is quite
+ * This is basically the same as field_attach_delete() except it only applies to
+ * a single field. The entity itself is not being deleted, and it is quite
  * possible that other field data will remain attached to it.
  *
  * @param $entity_type
@@ -922,7 +919,7 @@ function field_purge_data($entity_type, $entity, $field, $instance) {
 /**
  * Purges a field instance record from the database.
  *
- * This function assumes all data for the instance has already been purged, and
+ * This function assumes all data for the instance has already been purged and
  * should only be called by field_purge_batch().
  *
  * @param $instance
diff --git a/core/modules/field/field.default.inc b/core/modules/field/field.default.inc
index 1e1675c..543649b 100644
--- a/core/modules/field/field.default.inc
+++ b/core/modules/field/field.default.inc
@@ -20,15 +20,15 @@
  * @param $field
  *   The field structure for the operation.
  * @param $instance
- *   The instance structure for $field on $entity's bundle.
+ *   The instance structure for $field in $entity's bundle.
  * @param $langcode
- *   The language associated to $items.
+ *   The language associated with $items.
  * @param $items
  *   The field values. This parameter is altered by reference to receive the
  *   incoming form values.
  * @param $form
- *   The form structure where field elements are attached to. This might be a
- *   full form structure, or a sub-element of a larger form.
+ *   The form structure where field elements are attached. This might be a full
+ *   form structure, or a sub-element of a larger form.
  * @param $form_state
  *   The form state.
  */
@@ -44,12 +44,10 @@ function field_default_extract_form_values($entity_type, $entity, $field, $insta
 }
 
 /**
- * Generic field validation handler.
+ * Form validation handler for field elements.
  *
  * Possible error codes:
- * - 'field_cardinality': The number of values exceeds the field cardinality.
- *
- * @see _hook_field_validate()
+ * - field_cardinality: The number of values exceeds the field cardinality.
  *
  * @param $entity_type
  *   The type of $entity.
@@ -58,18 +56,18 @@ function field_default_extract_form_values($entity_type, $entity, $field, $insta
  * @param $field
  *   The field structure for the operation.
  * @param $instance
- *   The instance structure for $field on $entity's bundle.
+ *   The instance structure for $field in $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
  *   The array of errors, keyed by field name and by value delta, that have
- *   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.
+ *   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.
  */
 function field_default_validate($entity_type, $entity, $field, $instance, $langcode, $items, &$errors) {
   // Filter out empty values.
@@ -86,6 +84,28 @@ function field_default_validate($entity_type, $entity, $field, $instance, $langc
   }
 }
 
+/**
+ * Form submission handler for field elements.
+ *
+ * @param $entity_type
+ *   The type of $entity.
+ * @param $entity
+ *   The entity for the operation.
+ * @param $field
+ *   The field structure for the operation.
+ * @param $instance
+ *   The instance structure for $field in $entity's bundle.
+ * @param $langcode
+ *   The language associated with $items.
+ * @param $items
+ *   $entity->{$field['field_name']}[$langcode], or an empty array if unset.
+ * @param $form
+ *   The form to add field elements to.
+ * @param $form_state
+ *   An associative array containing the current state of the form.
+ *
+ * @see field_default_validate()
+ */
 function field_default_submit($entity_type, $entity, $field, $instance, $langcode, &$items, $form, &$form_state) {
   // Filter out empty values.
   $items = _field_filter_items($field, $items);
@@ -94,11 +114,24 @@ function field_default_submit($entity_type, $entity, $field, $instance, $langcod
 }
 
 /**
- * Default field 'insert' operation.
+ * Inserts a default value if no $entity->$field_name entry was provided.
  *
- * Insert default value if no $entity->$field_name entry was provided.
  * This can happen with programmatic saves, or on form-based creation where
- * the current user doesn't have 'edit' permission for the field.
+ * the current user doesn't have 'edit' permission for the field. This is the
+ * default field 'insert' operation.
+ *
+ * @param $entity_type
+ *   The type of $entity.
+ * @param $entity
+ *   The entity for the operation.
+ * @param $field
+ *   The field structure for the operation.
+ * @param $instance
+ *   The instance structure for $field in $entity's bundle.
+ * @param $langcode
+ *   The language associated with $items.
+ * @param $items
+ *   An array that this function will populate with default values.
  */
 function field_default_insert($entity_type, $entity, $field, $instance, $langcode, &$items) {
   // _field_invoke() populates $items with an empty array if the $entity has no
@@ -119,20 +152,20 @@ function field_default_insert($entity_type, $entity, $field, $instance, $langcod
  * @param $entity_type
  *   The type of $entity; e.g. 'node' or 'user'.
  * @param $entities
- *   An array of entities being displayed, keyed by entity id.
+ *   An 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.
+ *   The language associated with $items.
  * @param $items
  *   Array of field values already loaded for the entities, keyed by entity id.
  * @param $display
  *   Can be either:
- *   - the name of a view mode
- *   - or an array of display settings to use for display, as found in the
+ *   - The name of a view mode
+ *   - An array of display settings to use for display, as found in the
  *     'display' entry of $instance definitions.
  */
 function field_default_prepare_view($entity_type, $entities, $field, $instances, $langcode, &$items, $display) {
@@ -177,16 +210,19 @@ function field_default_prepare_view($entity_type, $entities, $field, $instances,
  * @param $field
  *   The field structure for the operation.
  * @param $instance
- *   An array containing each field on $entity's bundle.
+ *   An array containing each field in $entity's bundle.
  * @param $langcode
- *   The language associated to $items.
+ *   The language 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.
  * @param $display
  *   Can be either:
- *   - the name of a view mode;
- *   - or an array of custom display settings, as found in the 'display' entry
- *     of $instance definitions.
+ *   - The name of a view mode;
+ *   - An array of custom display settings, as found in the 'display' entry of
+ *     $instance definitions.
+ *
+ * @return
+ *   A renderable array.
  */
 function field_default_view($entity_type, $entity, $field, $instance, $langcode, $items, $display) {
   list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity);
@@ -246,15 +282,15 @@ function field_default_view($entity_type, $entity, $field, $instance, $langcode,
  * @param $field
  *   The field structure for the operation.
  * @param $instance
- *   The instance structure for $field on $entity's bundle.
+ *   The instance structure for $field in $entity's bundle.
  * @param $langcode
- *   The language the entity has to be translated in.
+ *   The language the entity has to be translated to.
  * @param $items
  *   $entity->{$field['field_name']}[$langcode], or an empty array if unset.
  * @param $source_entity
  *   The source entity holding the field values to be translated.
  * @param $source_langcode
- *   The source language from which translate.
+ *   The source language from which to translate.
  */
 function field_default_prepare_translation($entity_type, $entity, $field, $instance, $langcode, &$items, $source_entity, $source_langcode) {
   $field_name = $field['field_name'];
diff --git a/core/modules/field/field.form.inc b/core/modules/field/field.form.inc
index be3685d..4c3783d 100644
--- a/core/modules/field/field.form.inc
+++ b/core/modules/field/field.form.inc
@@ -6,7 +6,29 @@
  */
 
 /**
- * Create a separate form element for each field.
+ * Creates a separate form element for each field.
+ *
+ * @param $entity_type
+ *   The type of $entity; e.g., 'node' or 'user'.
+ * @param $entity
+ *   The entity the field belongs to.
+ * @param $field
+ *   The field structure.
+ * @param $instance
+ *   The instance structure.
+ * @param $langcode
+ *   The field language to fill-in with the default value.
+ * @param $items
+ *   An array of default field values.
+ * @param $form
+ *   The form to add field elements to.
+ * @param $form_state
+ *   An associative array containing the current state of the form.
+ * @param $get_delta
+ *   The delta of the field value, if applicable; otherwise NULL.
+ *
+ * @return
+ *   The new form element.
  */
 function field_default_form($entity_type, $entity, $field, $instance, $langcode, $items, &$form, &$form_state, $get_delta = NULL) {
   // This could be called with no entity, as when a UI module creates a
@@ -139,12 +161,28 @@ function field_default_form($entity_type, $entity, $field, $instance, $langcode,
 }
 
 /**
- * Special handling to create form elements for multiple values.
+ * Creates form elements for multiple values.
  *
  * Handles generic features for multiple fields:
- * - number of widgets
- * - AHAH-'add more' button
- * - drag-n-drop value reordering
+ * - Number of widgets.
+ * - AHAH-'add more' button.
+ * - Drag-n-drop value reordering.
+ *
+ * @param $field
+ *   The field structure.
+ * @param $instance
+ *   The instance structure.
+ * @param $langcode
+ *   The field language to fill-in with the default value.
+ * @param $items
+ *   An array of default field values.
+ * @param $form
+ *   The form to add field elements to.
+ * @param $form_state
+ *   An associative array containing the current state of the form.
+ *
+ * @return
+ *   An array of the new form elements.
  */
 function field_multiple_value_form($field, $instance, $langcode, $items, &$form, &$form_state) {
   $field_name = $field['field_name'];
@@ -257,14 +295,15 @@ function field_multiple_value_form($field, $instance, $langcode, $items, &$form,
 /**
  * Returns HTML for an individual form element.
  *
- * Combine multiple values into a table with drag-n-drop reordering.
- * TODO : convert to a template.
+ * Combines multiple values into a table with drag-n-drop reordering.
  *
  * @param $variables
  *   An associative array containing:
  *   - element: A render element representing the form element.
  *
  * @ingroup themeable
+ *
+ * @todo Convert to a template.
  */
 function theme_field_multiple_value_form($variables) {
   $element = $variables['element'];
@@ -331,11 +370,19 @@ function theme_field_multiple_value_form($variables) {
 }
 
 /**
- * #after_build callback for field elements in a form.
+ * After-build callback for field elements in a form.
  *
- * This stores the final location of the field within the form structure so
- * that field_default_form_errors() can assign validation errors to the right
- * form element.
+ * This stores the final location of the field within the form structure so that
+ * field_default_form_errors() can assign validation errors to the right form
+ * element.
+ *
+ * @param $element
+ *   The form element.
+ * @param $form_state
+ *   An associative array containing the current state of the form.
+ *
+ * @return
+ *   The $element array that was passed in as a parameter.
  *
  * @see field_default_form_errors()
  */
@@ -352,7 +399,24 @@ function field_form_element_after_build($element, &$form_state) {
 }
 
 /**
- * Transfer field-level validation errors to widgets.
+ * Transfers field-level validation errors to widgets.
+ *
+ * @param $entity_type
+ *   The type of $entity; e.g., 'node' or 'user'.
+ * @param $entity
+ *   The entity the field belongs to.
+ * @param $field
+ *   The field structure.
+ * @param $instance
+ *   The instance structure.
+ * @param $langcode
+ *   The field language to fill in with the default value.
+ * @param $items
+ *   An array of default field values.
+ * @param $form
+ *   The form to add field elements to.
+ * @param $form_state
+ *   An associative array containing the current state of the form.
  */
 function field_default_form_errors($entity_type, $entity, $field, $instance, $langcode, $items, $form, &$form_state) {
   $field_state = field_form_get_state($form['#parents'], $field['field_name'], $langcode, $form_state);
@@ -387,7 +451,7 @@ function field_default_form_errors($entity_type, $entity, $field, $instance, $la
 }
 
 /**
- * Submit handler for the "Add another item" button of a field form.
+ * Form submission handler for the "Add another item" button of a field form.
  *
  * This handler is run regardless of whether JS is enabled or not. It makes
  * changes to the form state. If the button was clicked with JS disabled, then
@@ -413,7 +477,7 @@ function field_add_more_submit($form, &$form_state) {
 }
 
 /**
- * Ajax callback in response to a new empty widget being added to the form.
+ * Ajax callback: Responds to a new empty widget being added to the form.
  *
  * This returns the new page content to replace the page content made obsolete
  * by the form submission.
@@ -458,12 +522,12 @@ function field_add_more_js($form, $form_state) {
  *
  * @return
  *   An array with the following key/data pairs:
- *   - field: the field definition array,
- *   - instance: the field instance definition array,
- *   - items_count: the number of widgets to display for the field,
- *   - array_parents: the location of the field's widgets within the $form
+ *   - field: The field definition array.
+ *   - instance: The field instance definition array.
+ *   - items_count: The number of widgets to display for the field.
+ *   - array_parents: The location of the field's widgets within the $form
  *     structure. This entry is populated at '#after_build' time.
- *   - errors: the array of field validation errors reported on the field. This
+ *   - errors: The array of field validation errors reported on the field. This
  *     entry is populated at field_attach_form_validate() time.
  *
  * @see field_form_set_state()
@@ -497,6 +561,16 @@ function field_form_set_state($parents, $field_name, $langcode, &$form_state, $f
 
 /**
  * Returns the location of processing information within $form_state.
+ *
+ * @param $parents
+ *   The array of #parents where the field lives in the form.
+ * @param $field_name
+ *   The field name.
+ * @param $langcode
+ *   The language in which the field values are entered.
+ *
+ * @return
+ *   The location of processing information within $form_state.
  */
 function _field_form_state_parents($parents, $field_name, $langcode) {
   // To ensure backwards compatibility on regular entity forms for widgets that
@@ -522,7 +596,7 @@ function _field_form_state_parents($parents, $field_name, $langcode) {
 /**
  * Retrieves the field definition for a widget's helper callbacks.
  *
- * Widgets helper element callbacks (such as #process, #element_validate,
+ * Widget helper element callbacks (such as #process, #element_validate,
  * #value_callback, ...) should use field_widget_field() and
  * field_widget_instance() instead of field_info_field() and
  * field_info_instance() when they need to access field or instance properties.
diff --git a/core/modules/field/field.info.inc b/core/modules/field/field.info.inc
index 78bc62e..9289bfb 100644
--- a/core/modules/field/field.info.inc
+++ b/core/modules/field/field.info.inc
@@ -8,11 +8,11 @@
 /**
  * @defgroup field_info Field Info API
  * @{
- * Obtain information about Field API configuration.
+ * Obtains information about Field API configuration.
  *
- * The Field Info API exposes information about field types, fields,
- * instances, bundles, widget types, display formatters, behaviors,
- * and settings defined by or with the Field API.
+ * The Field Info API exposes information about field types, fields, instances,
+ * bundles, widget types, display formatters, behaviors, and settings defined by
+ * or with the Field API.
  *
  * See @link field Field API @endlink for information about the other parts of
  * the Field API.
@@ -21,9 +21,8 @@
 /**
  * Clears the field info cache without clearing the field data cache.
  *
- * This is useful when deleted fields or instances are purged.  We
- * need to remove the purged records, but no actual field data items
- * are affected.
+ * This is useful when deleted fields or instances are purged. We need to remove
+ * the purged records, but no actual field data items are affected.
  */
 function field_info_cache_clear() {
   drupal_static_reset('field_view_mode_settings');
@@ -42,27 +41,27 @@ function field_info_cache_clear() {
  *
  * @return
  *   An associative array containing:
- *   - 'field types': Array of hook_field_info() results, keyed by field_type.
+ *   - field types: Array of hook_field_info() results, keyed by field_type.
  *     Each element has the following components: label, description, settings,
- *     instance_settings, default_widget, default_formatter, and behaviors
- *     from hook_field_info(), as well as module, giving the module that exposes
- *     the field type.
- *   - 'widget types': Array of hook_field_widget_info() results, keyed by
+ *     instance_settings, default_widget, default_formatter, and behaviors from
+ *     hook_field_info(), as well as module, giving the module that exposes the
+ *     field type.
+ *   - widget types: Array of hook_field_widget_info() results, keyed by
  *     widget_type. Each element has the following components: label, field
- *     types, settings, and behaviors from hook_field_widget_info(), as well
- *     as module, giving the module that exposes the widget type.
- *   - 'formatter types': Array of hook_field_formatter_info() results, keyed by
+ *     types, settings, and behaviors from hook_field_widget_info(), as well as
+ *     module, giving the module that exposes the widget type.
+ *   - formatter types: Array of hook_field_formatter_info() results, keyed by
  *     formatter_type. Each element has the following components: label, field
  *     types, and behaviors from hook_field_formatter_info(), as well as
  *     module, giving the module that exposes the formatter type.
- *   - 'storage types': Array of hook_field_storage_info() results, keyed by
+ *   - storage types: Array of hook_field_storage_info() results, keyed by
  *     storage type names. Each element has the following components: label,
  *     description, and settings from hook_field_storage_info(), as well as
  *     module, giving the module that exposes the storage type.
- *   - 'fieldable types': Array of hook_entity_info() results, keyed by
- *     entity_type. Each element has the following components: name, id key,
+ *   - fieldable types: Array of hook_entity_info() results, keyed by
+ *     entity_type. Each element has the following components: name, ID key,
  *     revision key, bundle key, cacheable, and bundles from hook_entity_info(),
- *     as well as module, giving the module that exposes the entity type.
+ *     as well as module, the module that exposes the entity type.
  *
  * @see _field_info_collate_types_reset()
  */
@@ -158,7 +157,7 @@ function _field_info_collate_types() {
 }
 
 /**
- * Clear collated information on field and widget types and related structures.
+ * Clears collated information on field and widget types and related structures.
  */
 function _field_info_collate_types_reset() {
   drupal_static_reset('_field_info_collate_types');
@@ -171,15 +170,15 @@ function _field_info_collate_types_reset() {
  *
  * @return
  *   An associative array containing:
- *   - fields: Array of existing fields, keyed by field ID. This element
- *     lists deleted and non-deleted fields, but not inactive ones.
- *     Each field has an additional element, 'bundles', which is an array
- *     of all non-deleted instances of that field.
- *   - field_ids: Array of field IDs, keyed by field name. This element
- *     only lists non-deleted, active fields.
- *   - instances: Array of existing instances, keyed by entity type, bundle
- *     name and field name. This element only lists non-deleted instances
- *     whose field is active.
+ *   - fields: Array of existing fields, keyed by field ID. This element lists
+ *     deleted and non-deleted fields, but not inactive ones. Each field has an
+ *     additional element, 'bundles', which is an array of all non-deleted
+ *     instances of that field.
+ *   - field_ids: Array of field IDs, keyed by field name. This element only
+ *     lists non-deleted, active fields.
+ *   - instances: Array of existing instances, keyed by entity type, bundle name
+ *     and field name. This element only lists non-deleted instances whose field
+ *     is active.
  *
  * @see _field_info_collate_fields_reset()
  */
@@ -253,7 +252,7 @@ function _field_info_collate_fields() {
 }
 
 /**
- * Clear collated information on existing fields and instances.
+ * Clears collated information on existing fields and instances.
  */
 function _field_info_collate_fields_reset() {
   drupal_static_reset('_field_info_collate_fields');
@@ -268,6 +267,9 @@ function _field_info_collate_fields_reset() {
  *
  * @param $field
  *   The raw field structure as read from the database.
+ *
+ * @return
+ *   The field array with storage and settings data added.
  */
 function _field_info_prepare_field($field) {
   // Make sure all expected field settings are present.
@@ -290,7 +292,7 @@ function _field_info_prepare_field($field) {
  *
  * Since the instance was last saved or updated, a number of things might have
  * changed: widgets or formatters disabled, new settings expected, new view
- * modes added...
+ * modes added, etc.
  *
  * @param $instance
  *   The raw instance structure as read from the database.
@@ -342,8 +344,10 @@ function _field_info_prepare_instance($instance, $field) {
  * @param $field
  *   The field structure for the instance.
  * @param $display
- *   Display specifications as found in
- *   $instance['display']['some_view_mode'].
+ *   Display specifications as found in $instance['display']['some_view_mode'].
+ *
+ * @return
+ *   The modified $display array.
  */
 function _field_info_prepare_instance_display($field, $display) {
   $field_type = field_info_field_types($field['type']);
@@ -377,6 +381,9 @@ function _field_info_prepare_instance_display($field, $display) {
  *   The field structure for the instance.
  * @param $widget
  *   Widget specifications as found in $instance['widget'].
+ *
+ * @return
+ *   The modified $widget array.
  */
 function _field_info_prepare_instance_widget($field, $widget) {
   $field_type = field_info_field_types($field['type']);
@@ -410,6 +417,9 @@ function _field_info_prepare_instance_widget($field, $widget) {
  *   The entity type.
  * @param $bundle
  *   The bundle name.
+ *
+ * @return
+ *   An array of data about extra fields.
  */
 function _field_info_prepare_extra_fields($extra_fields, $entity_type, $bundle) {
   $entity_type_info = entity_get_info($entity_type);
@@ -453,8 +463,8 @@ function _field_info_prepare_extra_fields($extra_fields, $entity_type, $bundle)
  * Determines the behavior of a widget with respect to an operation.
  *
  * @param $op
- *   The name of the operation. Currently supported: 'default value',
- *   'multiple values'.
+ *   The name of the operation. Currently supported: 'default value', 'multiple
+ *   values'.
  * @param $instance
  *   The field instance array.
  *
@@ -473,8 +483,7 @@ function field_behaviors_widget($op, $instance) {
  * Returns information about field types from hook_field_info().
  *
  * @param $field_type
- *   (optional) A field type name. If omitted, all field types will be
- *   returned.
+ *   (optional) A field type name. If omitted, all field types will be returned.
  *
  * @return
  *   Either a field type description, as provided by hook_field_info(), or an
@@ -552,8 +561,8 @@ function field_info_formatter_types($formatter_type = NULL) {
  *
  * @return
  *   Either a storage type description, as provided by
- *   hook_field_storage_info(), or an array of all existing storage types,
- *   keyed by storage type name.
+ *   hook_field_storage_info(), or an array of all existing storage types, keyed
+ *   by storage type name.
  */
 function field_info_storage_types($storage_type = NULL) {
   $info = _field_info_collate_types();
@@ -575,9 +584,9 @@ function field_info_storage_types($storage_type = NULL) {
  *   The type of entity; e.g. 'node' or 'user'.
  *
  * @return
- *   An array of bundles for the $entity_type keyed by bundle name,
- *   or, if no $entity_type was provided, the array of all existing bundles,
- *   keyed by entity type.
+ *   An array of bundles for the $entity_type keyed by bundle name, or, if no
+ *   $entity_type was provided, the array of all existing bundles, keyed by
+ *   entity type.
  */
 function field_info_bundles($entity_type = NULL) {
   $info = entity_get_info();
@@ -599,7 +608,7 @@ function field_info_bundles($entity_type = NULL) {
  * @return
  *   An array of field definitions, keyed by field name. Each field has an
  *   additional property, 'bundles', which is an array of all the bundles to
- *   which this field belongs keyed by entity type.
+ *   which this field belongs, keyed by entity type.
  */
 function field_info_fields() {
   $fields = array();
@@ -622,9 +631,9 @@ function field_info_fields() {
  *   use field_read_fields().
  *
  * @return
- *   The field array, as returned by field_read_fields(), with an
- *   additional element 'bundles', whose value is an array of all the bundles
- *   this field belongs to keyed by entity type.
+ *   The field array, as returned by field_read_fields(), with an additional
+ *   element 'bundles', whose value is an array of all the bundles this field
+ *   belongs to keyed by entity type.
  *
  * @see field_info_field_by_id()
  */
@@ -639,13 +648,13 @@ function field_info_field($field_name) {
  * Returns data about an individual field, given a field ID.
  *
  * @param $field_id
- *   The id of the field to retrieve. $field_id can refer to a
- *   deleted field, but not an inactive one.
+ *   The ID of the field to retrieve. $field_id can refer to a deleted field,
+ *   but not an inactive one.
  *
  * @return
- *   The field array, as returned by field_read_fields(), with an
- *   additional element 'bundles', whose value is an array of all the bundles
- *   this field belongs to.
+ *   The field array, as returned by field_read_fields(), with an additional
+ *   element 'bundles', whose value is an array of all the bundles this field
+ *   belongs to.
  *
  * @see field_info_field()
  */
@@ -686,8 +695,8 @@ function field_info_field_by_ids() {
  * @return
  *   If $entity_type is not set, return all instances keyed by entity type and
  *   bundle name. If $entity_type is set, return all instances for that entity
- *   type, keyed by bundle name. If $entity_type and $bundle_name are set, return
- *   all instances for that bundle.
+ *   type, keyed by bundle name. If $entity_type and $bundle_name are set,
+ *   return all instances for that bundle.
  */
 function field_info_instances($entity_type = NULL, $bundle_name = NULL) {
   $info = _field_info_collate_fields();
@@ -712,6 +721,9 @@ function field_info_instances($entity_type = NULL, $bundle_name = NULL) {
  *   The field name for the instance.
  * @param $bundle_name
  *   The bundle name for the instance.
+ *
+ * @return
+ *   An array of instance data.
  */
 function field_info_instance($entity_type, $field_name, $bundle_name) {
   $info = _field_info_collate_fields();
@@ -767,8 +779,8 @@ function field_info_instance($entity_type, $field_name, $bundle_name) {
  * @param $bundle
  *   The bundle name.
  * @param $context
- *   The context for which the list of pseudo-fields is requested. Either
- *   'form' or 'display'.
+ *   The context for which the list of pseudo-fields is requested. Either 'form'
+ *   or 'display'.
  *
  * @return
  *   The array of pseudo-field elements in the bundle.
@@ -794,6 +806,7 @@ function field_info_extra_fields($entity_type, $bundle, $context) {
  * @param $context
  *   The context for which the maximum weight is requested. Either 'form', or
  *   the name of a view mode.
+ *
  * @return
  *   The maximum weight of the entity's components, or NULL if no components
  *   were found.
diff --git a/core/modules/field/field.install b/core/modules/field/field.install
index dc7ec6c..3bb5da6 100644
--- a/core/modules/field/field.install
+++ b/core/modules/field/field.install
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Install, update and uninstall functions for the field module.
+ * Install, update, and uninstall functions for the Field module.
  */
 
 /**
@@ -167,7 +167,7 @@ function field_schema() {
 }
 
 /**
- * Utility function: create a field by writing directly to the database.
+ * Creates a field by writing directly to the database.
  *
  * @ingroup update-api-7.x-to-8.x
  */
@@ -237,7 +237,7 @@ function _update_7000_field_create_field(&$field) {
 }
 
 /**
- * Utility function: delete a field stored in SQL storage directly from the database.
+ * Deletes a field stored in SQL storage directly from the database.
  *
  * To protect user data, this function can only be used to delete fields once
  * all information it stored is gone. Delete all data from the
@@ -272,9 +272,9 @@ function _update_7000_field_delete_field($field_name) {
 
 
 /**
- * Utility function: delete an instance and all its data of a field stored in SQL Storage.
+ * Deletes an instance and all its data of a field stored in SQL Storage.
  *
- * BEWARE: this function deletes user data from the field storage tables.
+ * BEWARE: This function deletes user data from the field storage tables.
  *
  * @ingroup update-api-7.x-to-8.x
  */
@@ -298,9 +298,9 @@ function _update_7000_field_delete_instance($field_name, $entity_type, $bundle)
 }
 
 /**
- * Utility function: fetch all the field definitions from the database.
+ * Fetches all of the field definitions from the database.
  *
- * Warning: unlike the field_read_fields() API function, this function returns
+ * Warning: Unlike the field_read_fields() API function, this function returns
  * all fields by default, including deleted and inactive fields, unless
  * specified otherwise in the $conditions parameter.
  *
@@ -344,7 +344,7 @@ function _update_8000_field_read_fields(array $conditions = array(), $key = 'id'
 }
 
 /**
- * Utility function: write a field instance directly to the database.
+ * Writes a field instance directly to the database.
  *
  * @ingroup update-api-7.x-to-8.x
  */
diff --git a/core/modules/field/field.module b/core/modules/field/field.module
index 2f3041c..aeb7538 100644
--- a/core/modules/field/field.module
+++ b/core/modules/field/field.module
@@ -1,14 +1,14 @@
 <?php
 /**
  * @file
- * Attach custom data fields to Drupal entities.
+ * Attaches custom data fields to Drupal entities.
  */
 
 /**
- * Base class for all exceptions thrown by Field API functions.
+ * Allows all Field API exceptions to be caught by a single catch block.
  *
- * This class has no functionality of its own other than allowing all
- * Field API exceptions to be caught by a single catch block.
+ * This is a base class for all exceptions thrown by Field API functions. It has
+ * no functionality of its own.
  */
 class FieldException extends Exception {}
 
@@ -27,166 +27,162 @@ require_once DRUPAL_ROOT . '/core/modules/field/field.form.inc';
 /**
  * @defgroup field Field API
  * @{
- * Attach custom data fields to Drupal entities.
- *
- * The Field API allows custom data fields to be attached to Drupal
- * entities and takes care of storing, loading, editing, and rendering
- * field data. Any entity type (node, user, etc.) can use the Field
- * API to make itself "fieldable" and thus allow fields to be attached
- * to it. Other modules can provide a user interface for managing custom
- * fields via a web browser as well as a wide and flexible variety of
- * data type, form element, and display format capabilities.
- *
- * The Field API defines two primary data structures, Field and
- * Instance, and the concept of a Bundle. A Field defines a
- * particular type of data that can be attached to entities. A Field
- * Instance is a Field attached to a single Bundle. A Bundle is a set
- * of fields that are treated as a group by the Field Attach API and
- * is related to a single fieldable entity type.
- *
- * For example, suppose a site administrator wants Article nodes to
- * have a subtitle and photo. Using the Field API or Field UI module,
- * the administrator creates a field named 'subtitle' of type 'text'
- * and a field named 'photo' of type 'image'. The administrator
- * (again, via a UI) creates two Field Instances, one attaching the
- * field 'subtitle' to the 'node' bundle 'article' and one attaching
- * the field 'photo' to the 'node' bundle 'article'. When the node
- * system uses the Field Attach API to load all fields for an Article
- * node, it passes the node's entity type (which is 'node') and
- * content type (which is 'article') as the node's bundle.
- * field_attach_load() then loads the 'subtitle' and 'photo' fields
- * because they are both attached to the 'node' bundle 'article'.
+ * Attaches custom data fields to Drupal entities.
+ *
+ * The Field API allows custom data fields to be attached to Drupal entities and
+ * takes care of storing, loading, editing, and rendering field data. Any entity
+ * type (node, user, etc.) can use the Field API to make itself "fieldable" and
+ * thus allow fields to be attached to it. Other modules can provide a user
+ * interface for managing custom fields via a web browser as well as a wide and
+ * flexible variety of data type, form element, and display format capabilities.
+ *
+ * The Field API defines two primary data structures, Field and Instance, and
+ * the concept of a Bundle. A Field defines a particular type of data that can
+ * be attached to entities. A Field Instance is a Field attached to a single
+ * Bundle. A Bundle is a set of fields that are treated as a group by the Field
+ * Attach API and is related to a single fieldable entity type.
+ *
+ * For example, suppose a site administrator wants Article nodes to have a
+ * subtitle and photo. Using the Field API or Field UI module, the administrator
+ * creates a field named 'subtitle' of type 'text' and a field named 'photo' of
+ * type 'image'. The administrator (again, via a UI) creates two Field
+ * Instances, one attaching the field 'subtitle' to the 'node' bundle 'article'
+ * and one attaching the field 'photo' to the 'node' bundle 'article'. When the
+ * node system uses the Field Attach API to load all fields for an Article node,
+ * it passes the node's entity type (which is 'node') and content type (which is
+ * 'article') as the node's bundle. field_attach_load() then loads the
+ * 'subtitle' and 'photo' fields because they are both attached to the 'node'
+ * bundle 'article'.
  *
  * Field definitions are represented as an array of key/value pairs.
  *
  * array $field:
- * - id (integer, read-only): The primary identifier of the field. It is
+ * - id: (integer, read-only) The primary identifier of the field. It is
  *   assigned automatically by field_create_field().
- * - field_name (string): The name of the field. Each field name is unique
+ * - field_name: (string) The name of the field. Each field name is unique
  *   within Field API. When a field is attached to an entity, the field's data
  *   is stored in $entity->$field_name. Maximum length is 32 characters.
- * - type (string): The type of the field, such as 'text' or 'image'. Field
+ * - type: (string) The type of the field, such as 'text' or 'image'. Field
  *   types are defined by modules that implement hook_field_info().
- * - entity_types (array): The array of entity types that can hold instances
- *   of this field. If empty or not specified, the field can have instances
- *   in any entity type.
- * - cardinality (integer): The number of values the field can hold. Legal
+ * - entity_types: (array) The array of entity types that can hold instances of
+ *   this field. If empty or not specified, the field can have instances in any
+ *   entity type.
+ * - cardinality: (integer) The number of values the field can hold. Legal
  *   values are any positive integer or FIELD_CARDINALITY_UNLIMITED.
- * - translatable (integer): Whether the field is translatable.
- * - locked (integer): Whether or not the field is available for editing. If
+ * - translatable: (integer) Whether the field is translatable.
+ * - locked: (integer) Whether or not the field is available for editing. If
  *   TRUE, users can't change field settings or create new instances of the
  *   field in the UI. Defaults to FALSE.
- * - module (string, read-only): The name of the module that implements the
+ * - module: (string, read-only) The name of the module that implements the
  *   field type.
- * - active (integer, read-only): TRUE if the module that implements the field
+ * - active: (integer, read-only) TRUE if the module that implements the field
  *   type is currently enabled, FALSE otherwise.
- * - deleted (integer, read-only): TRUE if this field has been deleted, FALSE
+ * - deleted: (integer, read-only) TRUE if this field has been deleted, FALSE
  *   otherwise. Deleted fields are ignored by the Field Attach API. This
- *   property exists because fields can be marked for deletion but only
- *   actually destroyed by a separate garbage-collection process.
- * - columns (array, read-only): An array of the Field API columns used to
- *   store each value of this field. The column list may depend on field
- *   settings; it is not constant per field type. Field API column
- *   specifications are exactly like Schema API column specifications but,
- *   depending on the field storage module in use, the name of the column may
- *   not represent an actual column in an SQL database.
- * - indexes (array): An array of indexes on data columns, using the same
+ *   property exists because fields can be marked for deletion but only actually
+ *   destroyed by a separate garbage-collection process.
+ * - columns: (array, read-only) An array of the Field API columns used to store
+ *   each value of this field. The column list may depend on field settings; it
+ *   is not constant per field type. Field API column specifications are exactly
+ *   like Schema API column specifications but, depending onthe field storage
+ *   module in use, the name of the column may not represent an actual column in
+ *   an SQL database.
+ * - indexes: (array) An array of indexes on data columns, using the same
  *   definition format as Schema API index specifications. Only columns that
  *   appear in the 'columns' setting are allowed. Note that field types can
- *   specify default indexes, which can be modified or added to when
- *   creating a field.
+ *   specify default indexes, which can be modified or added to when creating a
+ *   field.
  * - foreign keys: (optional) An associative array of relations, using the same
  *   structure as the 'foreign keys' definition of hook_schema(). Note,
  *   however, that the field data is not necessarily stored in SQL. Also, the
  *   possible usage is limited, as you cannot specify another field as
  *   related, only existing SQL tables, such as filter formats.
- * - settings (array): A sub-array of key/value pairs of field-type-specific
+ * - settings: (array) A sub-array of key/value pairs of field-type-specific
  *   settings. Each field type module defines and documents its own field
  *   settings.
- * - storage (array): A sub-array of key/value pairs identifying the storage
- *   backend to use for the for the field:
- *   - type (string): The storage backend used by the field. Storage backends
+ * - storage: (array) A sub-array of key/value pairs identifying the storage
+ *   backend to use for the for the field.
+ *   - type: (string) The storage backend used by the field. Storage backends
  *     are defined by modules that implement hook_field_storage_info().
- *   - module (string, read-only): The name of the module that implements the
+ *   - module: (string, read-only) The name of the module that implements the
  *     storage backend.
- *   - active (integer, read-only): TRUE if the module that implements the
+ *   - active: (integer, read-only) TRUE if the module that implements the
  *     storage backend is currently enabled, FALSE otherwise.
- *   - settings (array): A sub-array of key/value pairs of settings. Each
+ *   - settings: (array) A sub-array of key/value pairs of settings. Each
  *     storage backend defines and documents its own settings.
  *
  * Field instance definitions are represented as an array of key/value pairs.
  *
  * array $instance:
- * - id (integer, read-only): The primary identifier of this field instance.
- *   It is assigned automatically by field_create_instance().
- * - field_id (integer, read-only): The foreign key of the field attached to
- *   the bundle by this instance. It is populated automatically by
+ * - id: (integer, read-only) The primary identifier of this field instance. It
+ *   is assigned automatically by field_create_instance().
+ * - field_id: (integer, read-only) The foreign key of the field attached to the
+ *   bundle by this instance. It is populated automatically by
  *   field_create_instance().
- * - field_name (string): The name of the field attached to the bundle by this
+ * - field_name: (string) The name of the field attached to the bundle by this
  *   instance.
- * - entity_type (string): The name of the entity type the instance is attached
+ * - entity_type: (string) The name of the entity type the instance is attached
  *   to.
- * - bundle (string): The name of the bundle that the field is attached to.
- * - label (string): A human-readable label for the field when used with this
- *   bundle. For example, the label will be the title of Form API elements
- *   for this instance.
- * - description (string): A human-readable description for the field when
- *   used with this bundle. For example, the description will be the help
- *   text of Form API elements for this instance.
- * - required (integer): TRUE if a value for this field is required when used
+ * - bundle: (string) The name of the bundle that the field is attached to.
+ * - label: (string) A human-readable label for the field when used with this
+ *   bundle. For example, the label will be the title of Form API elements for
+ *   this instance.
+ * - description: (string)A human-readable description for the field when used
+ *   with this bundle. For example, the description will be the help text of
+ *   Form API elements for this instance.
+ * - required: (integer) TRUE if a value for this field is required when used
  *   with this bundle, FALSE otherwise. Currently, required-ness is only
  *   enforced during Form API operations, not by field_attach_load(),
  *   field_attach_insert(), or field_attach_update().
- * - default_value_function (string): The name of the function, if any, that
+ * - default_value_function: (string) The name of the function, if any, that
  *   will provide a default value.
- * - default_value (array): If default_value_function is not set, then fixed
+ * - default_value: (array) If default_value_function is not set, then fixed
  *   values can be provided.
- * - deleted (integer, read-only): TRUE if this instance has been deleted,
- *   FALSE otherwise. Deleted instances are ignored by the Field Attach API.
- *   This property exists because instances can be marked for deletion but
- *   only actually destroyed by a separate garbage-collection process.
- * - settings (array): A sub-array of key/value pairs of field-type-specific
+ * - deleted: (integer, read-only) TRUE if this instance has been deleted, FALSE
+ *   otherwise. Deleted instances are ignored by the Field Attach API. This
+ *   property exists because instances can be marked for deletion but only
+ *   actually destroyed by a separate garbage-collection process.
+ * - settings: (array) A sub-array of key/value pairs of field-type-specific
  *   instance settings. Each field type module defines and documents its own
  *   instance settings.
- * - widget (array): A sub-array of key/value pairs identifying the Form API
- *   input widget for the field when used by this bundle:
- *   - type (string): The type of the widget, such as text_textfield. Widget
+ * - widget: (array) A sub-array of key/value pairs identifying the Form API
+ *   input widget for the field when used by this bundle.
+ *   - type: (string) The type of the widget, such as text_textfield. Widget
  *     types are defined by modules that implement hook_field_widget_info().
- *   - settings (array): A sub-array of key/value pairs of
- *     widget-type-specific settings. Each field widget type module defines
- *     and documents its own widget settings.
- *   - weight (float): The weight of the widget relative to the other elements
+ *   - settings: (array) A sub-array of key/value pairs of widget-type-specific
+ *     settings. Each field widget type module defines and documents its own
+ *     widget settings.
+ *   - weight: (float) The weight of the widget relative to the other elements
  *     in entity edit forms.
- *   - module (string, read-only): The name of the module that implements the
+ *   - module: (string, read-only) The name of the module that implements the
  *     widget type.
- * - display (array): A sub-array of key/value pairs identifying the way field
+ * - display: (array) A sub-array of key/value pairs identifying the way field
  *   values should be displayed in each of the entity type's view modes, plus
  *   the 'default' mode. For each view mode, Field UI lets site administrators
  *   define whether they want to use a dedicated set of display options or the
- *   'default' options to reduce the number of displays to maintain as they
- *   add new fields. For nodes, on a fresh install, only the 'teaser' view
- *   mode is configured to use custom display options, all other view modes
- *   defined use the 'default' options by default. When programmatically
- *   adding field instances on nodes, it is therefore recommended to at least
- *   specify display options for 'default' and 'teaser':
- *   - default (array): A sub-array of key/value pairs describing the display
- *     options to be used when the field is being displayed in view modes
- *     that are not configured to use dedicated display options:
- *     - label (string): Position of the label. 'inline', 'above' and
- *       'hidden' are the values recognized by the default 'field' theme
- *       implementation.
- *     - type (string): The type of the display formatter, or 'hidden' for
- *       no display.
- *     - settings (array): A sub-array of key/value pairs of display
- *       options specific to the formatter.
- *     - weight (float): The weight of the field relative to the other entity
- *       components displayed in this view mode.
- *     - module (string, read-only): The name of the module which implements
- *       the display formatter.
- *   - some_mode: A sub-array of key/value pairs describing the display
- *     options to be used when the field is being displayed in the 'some_mode'
- *     view mode. Those options will only be actually applied at run time if
- *     the view mode is not configured to use default settings for this bundle:
+ *   'default' options to reduce the number of displays to maintain as they add
+ *   new fields. For nodes, on a fresh install, only the 'teaser' view mode is
+ *   configured to use custom display options, all other view modes defined use
+ *   the 'default' options by default. When programmatically adding field
+ *   instances on nodes, it is therefore recommended to at least specify display
+ *   options for 'default' and 'teaser'.
+ *   - default: (array) A sub-array of key/value pairs describing the display
+ *     options to be used when the field is being displayed in view modes that
+ *     are not configured to use dedicated display options.
+ *     - label: (string) Position of the label. 'inline', 'above' and 'hidden'
+ *       are the values recognized by the default 'field' theme implementation.
+ *     - type: (string) The type of the display formatter, or 'hidden' for no
+ *       display.
+ *     - settings: (array) A sub-array of key/value pairs of display options
+ *       specific to the formatter.
+ *       - weight: (float) The weight of the field relative to the other entity
+ *         components displayed in this view mode.
+ *       - module: (string, read-only) The name of the module which implements
+ *         the display formatter.
+ *   - some_mode: A sub-array of key/value pairs describing the display options
+ *     to be used when the field is being displayed in the 'some_mode' view
+ *     mode. Those options will only be actually applied at run time if the view
+ *     mode is not configured to use default settings for this bundle.
  *     - ...
  *   - other_mode:
  *     - ...
@@ -196,37 +192,34 @@ require_once DRUPAL_ROOT . '/core/modules/field/field.form.inc';
  *
  * Bundles are represented by two strings, an entity type and a bundle name.
  *
- * - @link field_types Field Types API @endlink. Defines field types,
- *   widget types, and display formatters. Field modules use this API
- *   to provide field types like Text and Node Reference along with the
- *   associated form elements and display formatters.
- *
- * - @link field_crud Field CRUD API @endlink. Create, updates, and
- *   deletes fields, bundles (a.k.a. "content types"), and instances.
- *   Modules use this API, often in hook_install(), to create
- *   custom data structures.
- *
- * - @link field_attach Field Attach API @endlink. Connects entity
- *   types to the Field API. Field Attach API functions load, store,
- *   generate Form API structures, display, and perform a variety of
- *   other functions for field data connected to individual entities.
- *   Fieldable entity types like node and user use this API to make
- *   themselves fieldable.
- *
- * - @link field_info Field Info API @endlink. Exposes information
- *   about all fields, instances, widgets, and related information
- *   defined by or with the Field API.
- *
- * - @link field_storage Field Storage API @endlink. Provides a
- *   pluggable back-end storage system for actual field data. The
- *   default implementation, field_sql_storage.module, stores field data
- *   in the local SQL database.
- *
- * - @link field_purge Field API bulk data deletion @endlink. Cleans
- *   up after bulk deletion operations such as field_delete_field()
- *   and field_delete_instance().
- *
- * - @link field_language Field language API @endlink. Provides native
+ * - @link field_types Field Types API @endlink: Defines field types, widget
+ *   types, and display formatters. Field modules use this API to provide field
+ *   types like Text and Node Reference along with the associated form elements
+ *   and display formatters.
+ *
+ * - @link field_crud Field CRUD API @endlink: Create, updates, and deletes
+ *   fields, bundles (a.k.a. "content types"), and instances. Modules use this
+ *   API, often in hook_install(), to create custom data structures.
+ *
+ * - @link field_attach Field Attach API @endlink: Connects entity types to the
+ *   Field API. Field Attach API functions load, store, generate Form API
+ *   structures, display, and perform a variety of other functions for field
+ *   data connected to individual entities. Fieldable entity types like node and
+ *   user use this API to make themselves fieldable.
+ *
+ * - @link field_info Field Info API @endlink: Exposes information about all
+ *   fields, instances, widgets, and related information defined by or with the
+ *   Field API.
+ *
+ * - @link field_storage Field Storage API @endlink: Provides a pluggable back
+ *   -end storage system for actual field data. The default implementation,
+ *   field_sql_storage.module, stores field data in the local SQL database.
+ *
+ * - @link field_purge Field API bulk data deletion @endlink: Cleans up after
+ *   bulk deletion operations such as field_delete_field() and
+ *   field_delete_instance().
+ *
+ * - @link field_language Field language API @endlink: Provides native
  *   multilingual support for the Field API.
  */
 
@@ -262,14 +255,14 @@ const FIELD_BEHAVIOR_DEFAULT = 0x0002;
 const FIELD_BEHAVIOR_CUSTOM = 0x0004;
 
 /**
- * Age argument for loading the most recent version of an entity's
- * field data with field_attach_load().
+ * Age argument for loading the most recent version of an entity's field data
+ * with field_attach_load().
  */
 const FIELD_LOAD_CURRENT = 'FIELD_LOAD_CURRENT';
 
 /**
- * Age argument for loading the version of an entity's field data
- * specified in the entity with field_attach_load().
+ * Age argument for loading the version of an entity's field data specified in
+ * the entity with field_attach_load().
  */
 const FIELD_LOAD_REVISION = 'FIELD_LOAD_REVISION';
 
@@ -345,7 +338,7 @@ function field_cron() {
 /**
  * Implements hook_system_info_alter().
  *
- * Goes through a list of all modules that provide a field type, and makes them
+ * Goes through a list of all modules that provide a field type and makes them
  * required if there are any active fields of that type.
  */
 function field_system_info_alter(&$info, $file, $type) {
@@ -482,7 +475,7 @@ function field_get_default_value($entity_type, $entity, $field, $instance, $lang
 }
 
 /**
- * Helper function to filter out empty field values.
+ * Filters out empty field values.
  *
  * @param $field
  *   The field definition.
@@ -505,8 +498,15 @@ function _field_filter_items($field, $items) {
 }
 
 /**
- * Helper function to sort items in a field according to
- * user drag-n-drop reordering.
+ * Sorts items in a field according to user drag-and-drop reordering.
+ *
+ * @param $field
+ *   The field definition.
+ * @param $items
+ *   The field values to sort.
+ *
+ * @return
+ *   The sorted array of field items.
  */
 function _field_sort_items($field, $items) {
   if (($field['cardinality'] > 1 || $field['cardinality'] == FIELD_CARDINALITY_UNLIMITED) && isset($items[0]['_weight'])) {
@@ -521,8 +521,9 @@ function _field_sort_items($field, $items) {
 }
 
 /**
- * Sort function for items order.
- * (copied form element_sort(), which acts on #weight keys)
+ * Callback for usort() within _field_sort_items().
+ *
+ * Copied form element_sort(), which acts on #weight keys.
  */
 function _field_sort_items_helper($a, $b) {
   $a_weight = (is_array($a) ? $a['_weight'] : 0);
@@ -531,7 +532,9 @@ function _field_sort_items_helper($a, $b) {
 }
 
 /**
- * Same as above, using ['_weight']['#value']
+ * Callback for usort() within theme_field_multiple_value_form().
+ *
+ * Sorts using ['_weight']['#value']
  */
 function _field_sort_items_value_helper($a, $b) {
   $a_weight = (is_array($a) && isset($a['_weight']['#value']) ? $a['_weight']['#value'] : 0);
@@ -714,7 +717,7 @@ function field_extra_fields_get_display($entity_type, $bundle, $view_mode) {
 }
 
 /**
- * Pre-render callback to adjust weights and visibility of non-field elements.
+ * Pre-render callback: Adjusts weights and visibility of non-field elements.
  */
 function _field_extra_fields_pre_render($elements) {
   $entity_type = $elements['#entity_type'];
@@ -744,7 +747,7 @@ function _field_extra_fields_pre_render($elements) {
 }
 
 /**
- * Clear the field info and field data caches.
+ * Clears the field info and field data caches.
  */
 function field_cache_clear() {
   cache('field')->flush();
@@ -752,25 +755,34 @@ function field_cache_clear() {
 }
 
 /**
+ * Filters an HTML string to prevent cross-site-scripting (XSS) vulnerabilities.
+ *
  * Like filter_xss_admin(), but with a shorter list of allowed tags.
  *
- * Used for items entered by administrators, like field descriptions,
- * allowed values, where some (mainly inline) mark-up may be desired
- * (so check_plain() is not acceptable).
+ * Used for items entered by administrators, like field descriptions, allowed
+ * values, where some (mainly inline) mark-up may be desired (so
+ * drupal_htmlspecialchars() is not acceptable).
+ *
+ * @param $string
+ *   The string with raw HTML in it.
+ *
+ * @return
+ *   An XSS safe version of $string, or an empty string if $string is not valid
+ *   UTF-8.
  */
 function field_filter_xss($string) {
   return filter_xss($string, _field_filter_xss_allowed_tags());
 }
 
 /**
- * List of tags allowed by field_filter_xss().
+ * Returns a list of tags allowed by field_filter_xss().
  */
 function _field_filter_xss_allowed_tags() {
   return array('a', 'b', 'big',  'code', 'del', 'em', 'i', 'ins',  'pre', 'q', 'small', 'span', 'strong', 'sub', 'sup', 'tt', 'ol', 'ul', 'li', 'p', 'br', 'img');
 }
 
 /**
- * Human-readable list of allowed tags, for display in help texts.
+ * Returns a human-readable list of allowed tags for display in help texts.
  */
 function _field_filter_xss_display_allowed_tags() {
   return '<' . implode('> <', _field_filter_xss_allowed_tags()) . '>';
@@ -782,7 +794,7 @@ function _field_filter_xss_display_allowed_tags() {
  * @param $entity_type
  *   The type of $entity; e.g., 'node' or 'user'.
  * @param $entity
- *   The entity containing the field to display. Must at least contain the id
+ *   The entity containing the field to display. Must at least contain the ID
  *   key and the field data to display.
  * @param $field_name
  *   The name of the field to display.
@@ -790,11 +802,12 @@ function _field_filter_xss_display_allowed_tags() {
  *   The field value to display, as found in
  *   $entity->field_name[$langcode][$delta].
  * @param $display
- *   Can be either the name of a view mode, or an array of display settings.
- *   See field_view_field() for more information.
+ *   Can be either the name of a view mode, or an array of display settings. See
+ *   field_view_field() for more information.
  * @param $langcode
- *   (Optional) The language of the value in $item. If not provided, the
- *   current language will be assumed.
+ *   (Optional) The language of the value in $item. If not provided, the current
+ *   language will be assumed.
+ *
  * @return
  *   A renderable array for the field value.
  */
@@ -841,7 +854,7 @@ function field_view_value($entity_type, $entity, $field_name, $item, $display =
  * @param $entity_type
  *   The type of $entity; e.g., 'node' or 'user'.
  * @param $entity
- *   The entity containing the field to display. Must at least contain the id
+ *   The entity containing the field to display. Must at least contain the ID
  *   key and the field data to display.
  * @param $field_name
  *   The name of the field to display.
@@ -849,28 +862,28 @@ function field_view_value($entity_type, $entity, $field_name, $item, $display =
  *   Can be either:
  *   - The name of a view mode. The field will be displayed according to the
  *     display settings specified for this view mode in the $instance
- *     definition for the field in the entity's bundle.
- *     If no display settings are found for the view mode, the settings for
- *     the 'default' view mode will be used.
+ *     definition for the field in the entity's bundle. If no display settings
+ *     are found for the view mode, the settings for the 'default' view mode
+ *     will be used.
  *   - An array of display settings, as found in the 'display' entry of
  *     $instance definitions. The following key/value pairs are allowed:
  *     - label: (string) Position of the label. The default 'field' theme
  *       implementation supports the values 'inline', 'above' and 'hidden'.
  *       Defaults to 'above'.
  *     - type: (string) The formatter to use. Defaults to the
- *       'default_formatter' for the field type, specified in
- *       hook_field_info(). The default formatter will also be used if the
- *       requested formatter is not available.
+ *       'default_formatter' for the field type, specified in hook_field_info().
+ *       The default formatter will also be used if the requested formatter is
+ *       not available.
  *     - settings: (array) Settings specific to the formatter. Defaults to the
- *       formatter's default settings, specified in
- *       hook_field_formatter_info().
+ *       formatter's default settings, specified in hook_field_formatter_info().
  *     - weight: (float) The weight to assign to the renderable element.
  *       Defaults to 0.
  * @param $langcode
  *   (Optional) The language code the field values are to be shown in. The
  *   site's current language fallback logic will be applied when no values are
- *   available for given language code. If no language code is provided the
+ *   available for the given language code. If no language code is provided the
  *   current language will be used.
+ *
  * @return
  *   A renderable array for the field value.
  *
@@ -946,10 +959,11 @@ function field_get_items($entity_type, $entity, $field_name, $langcode = NULL) {
 }
 
 /**
- * Determine whether a field has any data.
+ * Determines whether a field has any data.
  *
  * @param $field
  *   A field structure.
+ *
  * @return
  *   TRUE if the field has data for any entity; FALSE otherwise.
  */
@@ -963,12 +977,12 @@ function field_has_data($field) {
 }
 
 /**
- * Determine whether the user has access to a given field.
+ * Determines whether the user has access to a given field.
  *
  * @param string $op
  *   The operation to be performed. Possible values:
- *   - 'edit'
- *   - 'view'
+ *   - edit
+ *   - view
  * @param array $field
  *   The full field structure array for the field on which the operation is to
  *   be performed. See field_info_field().
@@ -980,8 +994,7 @@ function field_has_data($field) {
  *   (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; FALSE if the operation is denied.
  */
 function field_access($op, $field, $entity_type, $entity = NULL, $account = NULL) {
   global $user;
@@ -1001,13 +1014,14 @@ function field_access($op, $field, $entity_type, $entity = NULL, $account = NULL
 }
 
 /**
- * Helper function to extract the bundle name of from a bundle object.
+ * Extracts the bundle name from a bundle object.
  *
  * @param $entity_type
  *   The type of $entity; e.g., 'node' or 'user'.
  * @param $bundle
  *   The bundle object (or string if bundles for this entity type do not exist
  *   as standalone objects).
+ *
  * @return
  *   The bundle name.
  */
@@ -1136,8 +1150,8 @@ function template_process_field(&$variables, $hook) {
  * So, if the body field on the article content type needs customization, a
  * field--body--article.tpl.php file can be added within the theme's folder.
  * Because it's a template, it will result in slightly more time needed to
- * display that field, but it will not impact other fields, and therefore,
- * is unlikely to cause a noticeable change in website performance. A very rough
+ * display that field, but it will not impact other fields, and therefore, is
+ * unlikely to cause a noticeable change in website performance. A very rough
  * guideline is that if a page is being displayed with more than 100 fields and
  * they are all themed with a template instead of a function, it can add up to
  * 5% to the time it takes to display that page. This is a guideline only and
@@ -1146,7 +1160,8 @@ function template_process_field(&$variables, $hook) {
  *
  * @param $variables
  *   An associative array containing:
- *   - label_hidden: A boolean indicating to show or hide the field label.
+ *   - label_hidden: A boolean indicating whether to show or hide the field
+ *     label.
  *   - title_attributes: A string containing the attributes for the title.
  *   - label: The label for the field.
  *   - content_attributes: A string containing the attributes for the content's
diff --git a/core/modules/field/field.multilingual.inc b/core/modules/field/field.multilingual.inc
index f054bf1..7a53324 100644
--- a/core/modules/field/field.multilingual.inc
+++ b/core/modules/field/field.multilingual.inc
@@ -8,7 +8,7 @@
 /**
  * @defgroup field_language Field Language API
  * @{
- * Handling of multilingual fields.
+ * Handles multilingual fields.
  *
  * Fields natively implement multilingual support, and all fields use the
  * following structure:
@@ -32,10 +32,16 @@
  * module registering itself via hook_entity_info() to handle field
  * translations.
  *
+
  * By default, _field_invoke() and _field_invoke_multiple() are processing a
  * field in all available languages, unless they are given a language code
  * suggestion. Based on that suggestion, _field_language_suggestion() determines
  * the languages to act on.
+
+ * By default, _field_invoke() and _field_invoke_multiple() process a field in
+ * all available languages, unless they are given a language code suggestion.
+ * Based on that suggestion, _field_language_suggestion() determines the
+ * languages to act on.
  *
  * Most field_attach_*() functions act on all available language codes, except
  * for the following:
@@ -128,8 +134,7 @@ function field_available_languages($entity_type, $field) {
 }
 
 /**
- * Process the given language code suggestion based on the available language
- * codes.
+ * Process the language code suggestion based on the available language codes.
  *
  * If a non-empty language code suggestion is provided it must appear among the
  * available language codes, otherwise it will be ignored.
@@ -196,8 +201,8 @@ function field_is_translatable($entity_type, $field) {
 /**
  * Checks if a module is registered as a translation handler for a given entity.
  *
- * If no handler is passed, simply check if there is any translation handler
- * enabled for the given entity type.
+ * If no handler is passed, the function simply checks if there is any
+ * translation handler enabled for the given entity type.
  *
  * @param $entity_type
  *   The type of the entity whose fields are to be translated.
@@ -239,6 +244,7 @@ function field_has_translation_handler($entity_type, $handler = NULL) {
  * @param $default
  *   Whether to return the default language code or the current language code in
  *   case $langcode is invalid.
+ *
  * @return
  *   A valid language code.
  */
@@ -252,36 +258,34 @@ function field_valid_language($langcode, $default = TRUE) {
 }
 
 /**
- * Returns the display language code for the fields attached to the given
- * entity.
+ * Returns the display language code for the fields of the given entity.
  *
  * The actual language code for each given field is determined based on the
  * requested language code and the actual data available in the fields
- * themselves.
- * If there is no registered translation handler for the given entity type, the
- * display language code to be used is just LANGUAGE_NOT_SPECIFIED, as no other
- * language code is allowed by field_available_languages().
- *
- * If translation handlers are found, we let modules provide alternative display
- * language codes for fields not having the requested language code available.
- * Core language fallback rules are provided by locale_field_language_fallback()
- * which is called by locale_field_language_alter().
+ * themselves. If there is no registered translation handler for the given
+ * entity type, the display language code to be used is just
+ * LANGUAGE_NOT_SPECIFIED, as no other language code is allowed by
+ * field_available_languages(). If translation handlers are found, we let
+ * modules provide alternative display language codes for fields not having the
+ * requested language code available. Core language fallback rules are provided
+ * by locale_field_language_fallback(), which is called by
+ * locale_field_language_alter().
  *
  * @param $entity_type
  *   The type of $entity.
  * @param $entity
  *   The entity to be displayed.
  * @param $field_name
- *   (optional) The name of the field to be displayed. Defaults to NULL. If
- *   no value is specified, the display language codes for every field attached
+ *   (optional) The name of the field to be displayed. Defaults to NULL. If no
+ *   value is specified, the display language codes for every field attached
  *   to the given entity will be returned.
  * @param $langcode
  *   (optional) The language code $entity has to be displayed in. Defaults to
  *   NULL. If no value is given the current language will be used.
  *
  * @return
- *   A language code if a field name is specified, an array of language codes
- *   keyed by field name otherwise.
+ *   A language code if a field name is specified, otherwise an array of
+ *   language codes keyed by field name.
  */
 function field_language($entity_type, $entity, $field_name = NULL, $langcode = NULL) {
   $display_langcodes = &drupal_static(__FUNCTION__, array());
diff --git a/core/modules/field/modules/field_sql_storage/field_sql_storage.install b/core/modules/field/modules/field_sql_storage/field_sql_storage.install
index eac5292..2d32555 100644
--- a/core/modules/field/modules/field_sql_storage/field_sql_storage.install
+++ b/core/modules/field/modules/field_sql_storage/field_sql_storage.install
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Install, update and uninstall functions for the field_sql_storage module.
+ * Install, update, and uninstall functions for the Field SQL Storage module.
  */
 
 /**
@@ -25,7 +25,7 @@ function field_sql_storage_schema() {
 }
 
 /**
- * Utility function: write field data directly to SQL storage.
+ * Writes field data directly to SQL storage.
  *
  * @ingroup update-api-7.x-to-8.x
  */
diff --git a/core/modules/field/modules/field_sql_storage/field_sql_storage.module b/core/modules/field/modules/field_sql_storage/field_sql_storage.module
index 14e5745..cf78929 100644
--- a/core/modules/field/modules/field_sql_storage/field_sql_storage.module
+++ b/core/modules/field/modules/field_sql_storage/field_sql_storage.module
@@ -1,13 +1,14 @@
 <?php
 
-use Drupal\Core\Database\Database;
-use Drupal\Core\Database\Query\Select;
-
 /**
  * @file
- * Default implementation of the field storage API.
+ * Default implementation of the Field Storage API.
  */
 
+use Drupal\Core\Database\Database;
+use Drupal\Core\Database\Query\Select;
+
+
 /**
  * Implements hook_help().
  */
@@ -34,12 +35,13 @@ function field_sql_storage_field_storage_info() {
 }
 
 /**
- * Generate a table name for a field data table.
+ * Generates a table name for a field data table.
  *
  * @param $field
  *   The field structure.
+ *
  * @return
- *   A string containing the generated name for the database table
+ *   A string containing the generated name for the database table.
  */
 function _field_sql_storage_tablename($field) {
   if ($field['deleted']) {
@@ -51,12 +53,13 @@ function _field_sql_storage_tablename($field) {
 }
 
 /**
- * Generate a table name for a field revision archive table.
+ * Generates a table name for a field revision archive table.
  *
  * @param $name
  *   The field structure.
+ *
  * @return
- *   A string containing the generated name for the database table
+ *   A string containing the generated name for the database table.
  */
 function _field_sql_storage_revision_tablename($field) {
   if ($field['deleted']) {
@@ -68,40 +71,43 @@ function _field_sql_storage_revision_tablename($field) {
 }
 
 /**
- * Generate a column name for a field data table.
+ * Generates a column name for a field data table.
  *
  * @param $name
- *   The name of the field
+ *   The name of the field.
  * @param $column
- *   The name of the column
+ *   The name of the column.
+ *
  * @return
- *   A string containing a generated column name for a field data
- *   table that is unique among all other fields.
+ *   A string containing a generated column name for a field data table that is
+ *   unique among all other fields.
  */
 function _field_sql_storage_columnname($name, $column) {
   return $name . '_' . $column;
 }
 
 /**
- * Generate an index name for a field data table.
+ * Generates an index name for a field data table.
  *
  * @param $name
- *   The name of the field
+ *   The name of the field.
  * @param $column
- *   The name of the index
+ *   The name of the index.
+ *
  * @return
- *   A string containing a generated index name for a field data
- *   table that is unique among all other fields.
+ *   A string containing a generated index name for a field data table that is
+ *   unique among all other fields.
  */
 function _field_sql_storage_indexname($name, $index) {
   return $name . '_' . $index;
 }
 
 /**
- * Return the database schema for a field. This may contain one or
- * more tables. Each table will contain the columns relevant for the
- * specified field. Leave the $field's 'columns' and 'indexes' keys
- * empty to get only the base schema.
+ * Returns the database schema for a field.
+ *
+ * This may contain one or more tables. Each table will contain the columns
+ * relevant for the specified field. Leave the $field's 'columns' and 'indexes'
+ * keys empty to get only the base schema.
  *
  * @param $field
  *   The field structure for which to generate a database schema.
@@ -224,8 +230,8 @@ function field_sql_storage_field_storage_create_field($field) {
 /**
  * Implements hook_field_update_forbid().
  *
- * Forbid any field update that changes column definitions if there is
- * any data.
+ * Forbids any field update that changes column definitions if there is any
+ * data.
  */
 function field_sql_storage_field_update_forbid($field, $prior_field, $has_data) {
   if ($has_data && $field['columns'] != $prior_field['columns']) {
@@ -473,8 +479,7 @@ function field_sql_storage_field_storage_delete($entity_type, $entity, $fields)
 /**
  * Implements hook_field_storage_purge().
  *
- * This function deletes data from the database for a single field on
- * an entity.
+ * This function deletes data from the database for a single field on an entity.
  */
 function field_sql_storage_field_storage_purge($entity_type, $entity, $field, $instance) {
   list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity);
@@ -589,11 +594,11 @@ function field_sql_storage_field_storage_query(EntityFieldQuery $query) {
  * @param $entity_type
  *   The entity type for which the base table should be joined.
  * @param $field_base_table
- *   Name of a table in $select_query. As only INNER JOINs are used, it does
- *   not matter which.
+ *   Name of a table in $select_query. As only INNER JOINs are used, it does not
+ *   matter which.
  *
  * @return
- *   The name of the entity base table joined in.
+ *   The name of the entity base table that was joined in.
  */
 function _field_sql_storage_query_join_entity(Select $select_query, $entity_type, $field_base_table) {
   $entity_info = entity_get_info($entity_type);
@@ -711,8 +716,8 @@ function field_sql_storage_field_attach_rename_bundle($entity_type, $bundle_old,
 /**
  * Implements hook_field_storage_purge_field().
  *
- * All field data items and instances have already been purged, so all
- * that is left is to delete the table.
+ * All field data items and instances have already been purged, so all that is
+ * left is to delete the table.
  */
 function field_sql_storage_field_storage_purge_field($field) {
   $table_name = _field_sql_storage_tablename($field);
diff --git a/core/modules/field/modules/field_sql_storage/field_sql_storage.test b/core/modules/field/modules/field_sql_storage/field_sql_storage.test
index 87c388a..1cba241 100644
--- a/core/modules/field/modules/field_sql_storage/field_sql_storage.test
+++ b/core/modules/field/modules/field_sql_storage/field_sql_storage.test
@@ -4,10 +4,10 @@ use Drupal\Core\Database\Database;
 
 /**
  * @file
- * Tests for field_sql_storage.module.
+ * Tests for the Field SQL Storage module.
  *
- * Field_sql_storage.module implements the default back-end storage plugin
- * for the Field Strage API.
+ * Field SQL Storage module implements the default back-end storage plugin
+ * for the Field Storage API.
  */
 
 /**
@@ -39,8 +39,7 @@ class FieldSqlStorageTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Uses the mysql tables and records to verify
-   * field_load_revision works correctly.
+   * Uses the mysql tables and records to verify that field_load_revision works.
    */
   function testFieldAttachLoad() {
     $entity_type = 'test_entity';
@@ -108,8 +107,7 @@ class FieldSqlStorageTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Reads mysql to verify correct data is
-   * written when using insert and update.
+   * Reads mysql to verify correct data is written when using insert and update.
    */
   function testFieldAttachInsertAndUpdate() {
     $entity_type = 'test_entity';
@@ -285,7 +283,7 @@ class FieldSqlStorageTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Test trying to update a field with data.
+   * Tests trying to update a field with data.
    */
   function testUpdateFieldSchemaWithData() {
     // Create a decimal 5.2 field and add some data.
@@ -309,7 +307,7 @@ class FieldSqlStorageTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Test that failure to create fields is handled gracefully.
+   * Tests that failure to create a field is handled gracefully.
    */
   function testFieldUpdateFailure() {
     // Create a text field.
@@ -334,7 +332,7 @@ class FieldSqlStorageTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Test adding and removing indexes while data is present.
+   * Tests adding and removing indexes while data is present.
    */
   function testFieldUpdateIndexesWithData() {
 
@@ -379,7 +377,7 @@ class FieldSqlStorageTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Test the storage details.
+   * Tests the storage details.
    */
   function testFieldStorageDetails() {
     $current = _field_sql_storage_tablename($this->field);
@@ -407,7 +405,7 @@ class FieldSqlStorageTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Test foreign key support.
+   * Tests for foreign key support.
    */
   function testFieldSqlStorageForeignKeys() {
     // Create a decimal field.
diff --git a/core/modules/field/modules/list/list.install b/core/modules/field/modules/list/list.install
index c86a219..cf7fc23 100644
--- a/core/modules/field/modules/list/list.install
+++ b/core/modules/field/modules/list/list.install
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Install, update and uninstall functions for the list module.
+ * Install, update, and uninstall functions for the List module.
  */
 
 /**
diff --git a/core/modules/field/modules/list/list.module b/core/modules/field/modules/list/list.module
index c2bff2a..d851b8c 100644
--- a/core/modules/field/modules/list/list.module
+++ b/core/modules/field/modules/list/list.module
@@ -155,7 +155,7 @@ function list_field_settings_form($field, $instance, $has_data) {
 }
 
 /**
- * Element validate callback; check that the entered values are valid.
+ * Form validation handler for integer, float, and text list elements.
  */
 function list_allowed_values_setting_validate($element, &$form_state) {
   $field = $element['#field'];
@@ -198,8 +198,10 @@ function list_allowed_values_setting_validate($element, &$form_state) {
 }
 
 /**
-* Form element #value_callback: assembles the allowed values for 'boolean' fields.
-*/
+ * Form element #value_callback for boolean elements.
+ *
+ * Assembles the allowed values for boolean fields.
+ */
 function list_boolean_allowed_values_callback($element, $input, $form_state) {
   $on = drupal_array_get_nested_value($form_state['input'], $element['#on_parents']);
   $off = drupal_array_get_nested_value($form_state['input'], $element['#off_parents']);
@@ -245,7 +247,7 @@ function list_allowed_values($field) {
 }
 
 /**
- * Parses a string of 'allowed values' into an array.
+ * Parses a string of allowed values into an array.
  *
  * @param $string
  *   The list of allowed values in string format described in
@@ -316,9 +318,9 @@ function list_extract_allowed_values($string, $field_type, $generate_keys) {
 }
 
 /**
- * Generates a string representation of an array of 'allowed values'.
+ * Generates a string representation of an array of allowed values.
  *
- * This string format is suitable for edition in a textarea.
+ * This string format is suitable for editing in a textarea.
  *
  * @param $values
  *   An array of values, where array keys are values and array values are
@@ -352,6 +354,14 @@ function list_field_update_forbid($field, $prior_field, $has_data) {
 
 /**
  * Checks if a list of values are being used in actual field values.
+ *
+ * @param $field
+ *   The field definition.
+ * @param $values
+ *   An array of values to check for.
+ *
+ * @return
+ *   TRUE if any of the values are being used; FALSE otherwise.
  */
 function _list_values_in_use($field, $values) {
   if ($values) {
@@ -370,7 +380,7 @@ function _list_values_in_use($field, $values) {
  * Implements hook_field_validate().
  *
  * Possible error codes:
- * - 'list_illegal_value': The value is not part of the list of allowed values.
+ * - list_illegal_value: The value is not part of the list of allowed values.
  */
 function list_field_validate($entity_type, $entity, $field, $instance, $langcode, $items, &$errors) {
   $allowed_values = list_allowed_values($field);
@@ -399,8 +409,8 @@ function list_field_is_empty($item, $field) {
 /**
  * Implements hook_field_widget_info_alter().
  *
- * The List module does not implement widgets of its own, but reuses the
- * widgets defined in options.module.
+ * The List module does not implement widgets of its own, but reuses the widgets
+ * defined in options.module.
  *
  * @see list_options_list()
  */
diff --git a/core/modules/field/modules/list/tests/list.test b/core/modules/field/modules/list/tests/list.test
index 988f6a3..3bd12db 100644
--- a/core/modules/field/modules/list/tests/list.test
+++ b/core/modules/field/modules/list/tests/list.test
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Tests for list.module.
+ * Tests for the List module.
  */
 
 /**
diff --git a/core/modules/field/modules/number/number.install b/core/modules/field/modules/number/number.install
index 02c7a30..3c4ae7f 100644
--- a/core/modules/field/modules/number/number.install
+++ b/core/modules/field/modules/number/number.install
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Install, update and uninstall functions for the number module.
+ * Install, update, and uninstall functions for the Number module.
  */
 
 /**
diff --git a/core/modules/field/modules/number/number.module b/core/modules/field/modules/number/number.module
index 23725f5..6e451a3 100644
--- a/core/modules/field/modules/number/number.module
+++ b/core/modules/field/modules/number/number.module
@@ -129,8 +129,8 @@ function number_field_instance_settings_form($field, $instance) {
  * Implements hook_field_validate().
  *
  * Possible error codes:
- * - 'number_min': The value is less than the allowed minimum value.
- * - 'number_max': The value is greater than the allowed maximum value.
+ * - number_min: The value is less than the allowed minimum value.
+ * - number_max: The value is greater than the allowed maximum value.
  */
 function number_field_validate($entity_type, $entity, $field, $instance, $langcode, $items, &$errors) {
   foreach ($items as $delta => $item) {
@@ -363,7 +363,7 @@ function number_field_widget_form(&$form, &$form_state, $field, $instance, $lang
 }
 
 /**
- * FAPI validation of an individual number element.
+ * Form validation handler for an individual number element.
  */
 function number_field_widget_validate($element, &$form_state) {
   $field = field_widget_field($element, $form_state);
diff --git a/core/modules/field/modules/number/number.test b/core/modules/field/modules/number/number.test
index 4a4f05f..c45a708 100644
--- a/core/modules/field/modules/number/number.test
+++ b/core/modules/field/modules/number/number.test
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Tests for number.module.
+ * Tests for the Number module.
  */
 
 /**
diff --git a/core/modules/field/modules/options/options.api.php b/core/modules/field/modules/options/options.api.php
index d1ac0db..306a8a3 100644
--- a/core/modules/field/modules/options/options.api.php
+++ b/core/modules/field/modules/options/options.api.php
@@ -9,25 +9,26 @@
  * Returns the list of options to be displayed for a field.
  *
  * Field types willing to enable one or several of the widgets defined in
- * options.module (select, radios/checkboxes, on/off checkbox) need to
- * implement this hook to specify the list of options to display in the
- * widgets.
+ * options.module (select, radios/checkboxes, on/off checkbox) need to implement
+ * this hook to specify the list of options to display in the widgets.
  *
  * @param $field
  *   The field definition.
  * @param $instance
- *   The instance definition. It is recommended to only use instance level
- *   properties to filter out values from a list defined by field level
+ *   The instance definition. It is recommended to only use instance-level
+ *   properties to filter out values from a list defined by field-level
  *   properties.
  *
  * @return
- *   The array of options for the field. Array keys are the values to be
- *   stored, and should be of the data type (string, number...) expected by
- *   the first 'column' for the field type. Array values are the labels to
- *   display within the widgets. The labels should NOT be sanitized,
- *   options.module takes care of sanitation according to the needs of each
- *   widget. The HTML tags defined in _field_filter_xss_allowed_tags() are
- *   allowed, other tags will be filtered.
+ *   The array of options for the field. Array keys are the values to be stored,
+ *   and should be of the data type (string, number...) expected by the first
+ *   'column' for the field type. Array values are the labels to display within
+ *   the widgets. The labels should NOT be sanitized; options.module takes care
+ *   of sanitation according to the needs of each widget. The HTML tags defined
+ *   in _field_filter_xss_allowed_tags() are allowed; other tags will be
+ *   filtered.
+ *
+ * @ingroup hooks
  */
 function hook_options_list($field, $instance) {
   // Sample structure.
diff --git a/core/modules/field/modules/options/options.module b/core/modules/field/modules/options/options.module
index 04b88d8..ef72cfa 100644
--- a/core/modules/field/modules/options/options.module
+++ b/core/modules/field/modules/options/options.module
@@ -2,7 +2,9 @@
 
 /**
  * @file
- * Defines selection, check box and radio button widgets for text and numeric fields.
+ * Defines select, checkbox, and radio button widgets.
+ *
+ * Text and numeric fields may use these widgets.
  */
 
 /**
@@ -34,8 +36,9 @@ function options_theme() {
  *
  * Field type modules willing to use those widgets should:
  * - Use hook_field_widget_info_alter() to append their field own types to the
- *   list of types supported by the widgets,
+ *   list of types supported by the widgets.
  * - Implement hook_options_list() to provide the list of options.
+ *
  * See list.module.
  */
 function options_field_widget_info() {
@@ -163,7 +166,7 @@ function options_field_widget_settings_form($field, $instance) {
 }
 
 /**
- * Form element validation handler for options element.
+ * Form element validation handler for options elements.
  */
 function options_field_widget_validate($element, &$form_state) {
   if ($element['#required'] && $element['#value'] == '_none') {
@@ -177,6 +180,18 @@ function options_field_widget_validate($element, &$form_state) {
 
 /**
  * Describes the preparation steps required by each widget.
+ *
+ * @param $type
+ *   The type of widget: select, buttons, or onoff.
+ * @param $multiple
+ *   TRUE if the field allows multiple values; FALSE otherwise.
+ * @param $required
+ *   TRUE if a value is required for the field; FALSE otherwise.
+ * @param $has_value
+ *   TRUE if a value is selected.
+ *
+ * @return
+ *   An array of properties for the widget.
  */
 function _options_properties($type, $multiple, $required, $has_value) {
   $base = array(
@@ -236,6 +251,16 @@ function _options_properties($type, $multiple, $required, $has_value) {
 
 /**
  * Collects the options for a field.
+ *
+ * @param $field
+ *   The field structure.
+ * @param $instance
+ *   The instance structure.
+ * @param $properties
+ *   An array containing the properties of the widget.
+ *
+ * @return
+ *   The option array for the field.
  */
 function _options_get_options($field, $instance, $properties) {
   // Get the list of options.
@@ -257,9 +282,12 @@ function _options_get_options($field, $instance, $properties) {
 }
 
 /**
- * Sanitizes the options.
+ * Sanitizes the options recursively to support optgroups.
  *
- * The function is recursive to support optgroups.
+ * @param $options
+ *   The option array.
+ * @param $properties
+ *   An array containing the properties of the widget.
  */
 function _options_prepare_options(&$options, $properties) {
   foreach ($options as $value => $label) {
@@ -280,6 +308,18 @@ function _options_prepare_options(&$options, $properties) {
 
 /**
  * Transforms stored field values into the format the widgets need.
+ *
+ * @param $items
+ *   An array of stored field values.
+ * @param $options
+ *   The options array.
+ * @param $column
+ *   The field storage column of the field.
+ * @param $properties
+ *   An array containing the properties of the widget.
+ *
+ * @return
+ *   An array of values in the format used by widgets.
  */
 function _options_storage_to_form($items, $options, $column, $properties) {
   $items_transposed = options_array_transpose($items);
@@ -296,6 +336,12 @@ function _options_storage_to_form($items, $options, $column, $properties) {
 
 /**
  * Transforms submitted form values into field storage format.
+ *
+ * @param $element
+ *   The form element.
+ *
+ * @return
+ *   An array of field values in field storage format.
  */
 function _options_form_to_storage($element) {
   $values = array_values((array) $element['#value']);
@@ -327,13 +373,14 @@ function _options_form_to_storage($element) {
 /**
  * Manipulates a 2D array to reverse rows and columns.
  *
- * The default data storage for fields is delta first, column names second.
- * This is sometimes inconvenient for field modules, so this function can be
- * used to present the data in an alternate format.
+ * The default data storage for fields is delta first, column names second. This
+ * is sometimes inconvenient for field modules, so this function can be used to
+ * present the data in an alternate format.
  *
  * @param $array
- *   The array to be transposed. It must be at least two-dimensional, and
- *   the subarrays must all have the same keys or behavior is undefined.
+ *   The array to be transposed. It must be at least two-dimensional, and the
+ *   subarrays must all have the same keys or behavior is undefined.
+ *
  * @return
  *   The transposed array.
  */
@@ -385,9 +432,10 @@ function options_field_widget_error($element, $error, $form, &$form_state) {
 }
 
 /**
- * Returns HTML for the label for the empty value for options that are not required.
+ * Returns HTML for the label for the empty value for non-required options.
  *
- * The default theme will display N/A for a radio list and '- None -' for a select.
+ * The default theme will display N/A for a radio list and '- None -' for a
+ * select.
  *
  * @param $variables
  *   An associative array containing:
diff --git a/core/modules/field/modules/options/options.test b/core/modules/field/modules/options/options.test
index b945949..1f765f3 100644
--- a/core/modules/field/modules/options/options.test
+++ b/core/modules/field/modules/options/options.test
@@ -1,8 +1,8 @@
 <?php
 
 /**
- * @file 
- * Tests for options.module.
+ * @file
+ * Tests for the Options module.
  */
 
 class OptionsWidgetsTestCase extends FieldTestCase {
diff --git a/core/modules/field/modules/text/text.install b/core/modules/field/modules/text/text.install
index 1b8d00b..a2ef0cf 100644
--- a/core/modules/field/modules/text/text.install
+++ b/core/modules/field/modules/text/text.install
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Install, update and uninstall functions for the text module.
+ * Install, update, and uninstall functions for the Text module.
  */
 
 /**
diff --git a/core/modules/field/modules/text/text.module b/core/modules/field/modules/text/text.module
index 985fa9b..7f60f70 100644
--- a/core/modules/field/modules/text/text.module
+++ b/core/modules/field/modules/text/text.module
@@ -22,12 +22,12 @@ function text_help($path, $arg) {
  * Implements hook_field_info().
  *
  * Field settings:
- *   - max_length: the maximum length for a varchar field.
+ *   - max_length: The maximum length for a varchar field.
  * Instance settings:
- *   - text_processing: whether text input filters should be used.
- *   - display_summary: whether the summary field should be displayed.
- *     When empty and not displayed the summary will take its value from the
- *     trimmed value of the main text field.
+ *   - text_processing: Whether text input filters should be used.
+ *   - display_summary: Whether the summary field should be displayed. When
+ *     empty and not displayed the summary will take its value from the trimmed
+ *     value of the main text field.
  */
 function text_field_info() {
   return array(
@@ -112,8 +112,8 @@ function text_field_instance_settings_form($field, $instance) {
  * Implements hook_field_validate().
  *
  * Possible error codes:
- * - 'text_value_max_length': The value exceeds the maximum length.
- * - 'text_summary_max_length': The summary exceeds the maximum length.
+ * - text_value_max_length: The value exceeds the maximum length.
+ * - text_summary_max_length: The summary exceeds the maximum length.
  */
 function text_field_validate($entity_type, $entity, $field, $instance, $langcode, $items, &$errors) {
   foreach ($items as $delta => $item) {
@@ -144,9 +144,9 @@ function text_field_validate($entity_type, $entity, $field, $instance, $langcode
 /**
  * Implements hook_field_load().
  *
- * Where possible, generate the sanitized version of each field early so that
- * it is cached in the field cache. This avoids looking up from the filter cache
- * separately.
+ * Where possible, the function generates the sanitized version of each field
+ * early so that it is cached in the field cache. This avoids the need to look
+ * up the field in the filter cache separately.
  *
  * @see text_field_formatter_view()
  */
@@ -301,14 +301,14 @@ function text_field_formatter_view($entity_type, $entity, $field, $instance, $la
  * @param $instance
  *   The instance definition.
  * @param $langcode
- *  The language associated to $item.
+ *  The language associated with $item.
  * @param $item
  *   The field value to sanitize.
  * @param $column
  *   The column to sanitize (either 'value' or 'summary').
  *
  * @return
- *  The sanitized string.
+ *   The sanitized string.
  */
 function _text_sanitize($instance, $langcode, $item, $column) {
   // If the value uses a cacheable text format, text_field_load() precomputes
@@ -320,27 +320,25 @@ function _text_sanitize($instance, $langcode, $item, $column) {
 }
 
 /**
- * Generate a trimmed, formatted version of a text field value.
+ * Generates a trimmed, formatted version of a text field value.
  *
  * If the end of the summary is not indicated using the <!--break--> delimiter
  * then we generate the summary automatically, trying to end it at a sensible
- * place such as the end of a paragraph, a line break, or the end of a
- * sentence (in that order of preference).
+ * place such as the end of a paragraph, a line break, or the end of a sentence
+ * (in that order of preference).
  *
  * @param $text
  *   The content for which a summary will be generated.
  * @param $format
- *   The format of the content.
- *   If the PHP filter is present and $text contains PHP code, we do not
- *   split it up to prevent parse errors.
- *   If the line break filter is present then we treat newlines embedded in
- *   $text as line breaks.
+ *   The format of the content. If the PHP filter is present and $text contains
+ *   PHP code, we do not split it up to prevent parse errors. If the line break
+ *   filter is present then we treat newlines embedded in $text as line breaks.
  *   If the htmlcorrector filter is present, it will be run on the generated
  *   summary (if different from the incoming $text).
  * @param $size
- *   The desired character length of the summary. If omitted, the default
- *   value will be used. Ignored if the special delimiter is present
- *   in $text.
+ *   The desired character length of the summary. If omitted, the default value
+ *   will be used. Ignored if the special delimiter is present in $text.
+ *
  * @return
  *   The generated summary.
  */
diff --git a/core/modules/field/modules/text/text.test b/core/modules/field/modules/text/text.test
index 0dbaccc..8176207 100644
--- a/core/modules/field/modules/text/text.test
+++ b/core/modules/field/modules/text/text.test
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Tests for text.module.
+ * Tests for the Text module.
  */
 
 class TextFieldTestCase extends DrupalWebTestCase {
diff --git a/core/modules/field/tests/field.test b/core/modules/field/tests/field.test
index 61c7073..9806557 100644
--- a/core/modules/field/tests/field.test
+++ b/core/modules/field/tests/field.test
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Tests for field.module.
+ * Tests for the Field module.
  */
 
 /**
diff --git a/core/modules/field/tests/field_test.entity.inc b/core/modules/field/tests/field_test.entity.inc
index 52ed3fc..9e373ca 100644
--- a/core/modules/field/tests/field_test.entity.inc
+++ b/core/modules/field/tests/field_test.entity.inc
@@ -315,7 +315,7 @@ function field_test_entity_save(&$entity) {
 }
 
 /**
- * Menu callback: displays the 'Add new test_entity' form.
+ * Menu callback: Displays the 'Add new test_entity' form.
  */
 function field_test_entity_add($fttype) {
   $fttype = str_replace('-', '_', $fttype);
@@ -325,7 +325,7 @@ function field_test_entity_add($fttype) {
 }
 
 /**
- * Menu callback: displays the 'Edit exiisting test_entity' form.
+ * Menu callback: Displays the 'Edit exiisting test_entity' form.
  */
 function field_test_entity_edit($entity) {
   drupal_set_title(t('test_entity @ftid revision @ftvid', array('@ftid' => $entity->ftid, '@ftvid' => $entity->ftvid)), PASS_THROUGH);
@@ -375,14 +375,14 @@ function field_test_entity_form($form, &$form_state, $entity, $add = FALSE) {
 }
 
 /**
- * Validate handler for field_test_entity_form().
+ * Form validation handler for field_test_entity_form().
  */
 function field_test_entity_form_validate($form, &$form_state) {
   entity_form_field_validate('test_entity', $form, $form_state);
 }
 
 /**
- * Submit handler for field_test_entity_form().
+ * Form submission handler for field_test_entity_form().
  */
 function field_test_entity_form_submit($form, &$form_state) {
   $entity = field_test_entity_form_submit_build_test_entity($form, $form_state);
@@ -450,7 +450,7 @@ function field_test_entity_nested_form($form, &$form_state, $entity_1, $entity_2
 }
 
 /**
- * Validate handler for field_test_entity_nested_form().
+ * Form validation handler for field_test_entity_nested_form().
  */
 function field_test_entity_nested_form_validate($form, &$form_state) {
   $entity_1 = (object) $form_state['values'];
@@ -461,7 +461,7 @@ function field_test_entity_nested_form_validate($form, &$form_state) {
 }
 
 /**
- * Submit handler for field_test_entity_nested_form().
+ * Form submission handler for field_test_entity_nested_form().
  */
 function field_test_entity_nested_form_submit($form, &$form_state) {
   $entity_1 = (object) $form_state['values'];
diff --git a/core/modules/field/tests/field_test.field.inc b/core/modules/field/tests/field_test.field.inc
index cc76a99..e0dc853 100644
--- a/core/modules/field/tests/field_test.field.inc
+++ b/core/modules/field/tests/field_test.field.inc
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Defines a field type and its formatters and widgets.
+ * Defines a field type, and its formatters and widgets.
  */
 
 /**
diff --git a/core/modules/field/tests/field_test.install b/core/modules/field/tests/field_test.install
index 5957561..f9c9321 100644
--- a/core/modules/field/tests/field_test.install
+++ b/core/modules/field/tests/field_test.install
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Install, update and uninstall functions for the field_test module.
+ * Install, update, and uninstall functions for the field_test module.
  */
 
 /**
diff --git a/core/modules/field/tests/field_test.module b/core/modules/field/tests/field_test.module
index 90e25c8..02d49a8 100644
--- a/core/modules/field/tests/field_test.module
+++ b/core/modules/field/tests/field_test.module
@@ -123,18 +123,16 @@ function field_test_field_language_alter(&$display_langcode, $context) {
 /**
  * Store and retrieve keyed data for later verification by unit tests.
  *
- * This function is a simple in-memory key-value store with the
- * distinction that it stores all values for a given key instead of
- * just the most recently set value. field_test module hooks call
- * this function to record their arguments, keyed by hook name. The
- * unit tests later call this function to verify that the correct
- * hooks were called and were passed the correct arguments.
+ * This function is a simple in-memory key-value store with the distinction that
+ * it stores all values for a given key instead of just the most recently set
+ * value. field_test module hooks call this function to record their arguments,
+ * keyed by hook name. The unit tests later call this function to verify that
+ * the correct hooks were called and were passed the correct arguments.
  *
- * This function ignores all calls until the first time it is called
- * with $key of NULL. Each time it is called with $key of NULL, it
- * erases all previously stored data from its internal cache, but also
- * returns the previously stored data to the caller. A typical usage
- * scenario is:
+ * This function ignores all calls until the first time it is called with $key
+ * of NULL. Each time it is called with $key of NULL, it erases all previously
+ * stored data from its internal cache, but also returns the previously stored
+ * data to the caller. A typical usage scenario is:
  *
  * @code
  *   // calls to field_test_memorize() here are ignored
@@ -158,8 +156,8 @@ function field_test_field_language_alter(&$display_langcode, $context) {
  * @param $value
  *   A value to store for $key.
  * @return
- *   An array mapping each $key to an array of each $value passed in
- *   for that key.
+ *   An array mapping each $key to an array of each $value passed in for that
+ *   key.
  */
 function field_test_memorize($key = NULL, $value = NULL) {
   $memorize = &drupal_static(__FUNCTION__, NULL);
diff --git a/core/modules/field/tests/field_test.storage.inc b/core/modules/field/tests/field_test.storage.inc
index eaa0851..49b1b32 100644
--- a/core/modules/field/tests/field_test.storage.inc
+++ b/core/modules/field/tests/field_test.storage.inc
@@ -66,7 +66,7 @@ function field_test_field_storage_details_alter(&$details, $field) {
 }
 
 /**
- * Helper function: stores or retrieves data from the 'storage backend'.
+ * Helper function: Stores or retrieves data from the 'storage backend'.
  */
 function _field_test_storage_data($data = NULL) {
   if (!isset($data)) {
diff --git a/core/modules/field/theme/field.tpl.php b/core/modules/field/theme/field.tpl.php
index a6d7a96..5c6f5a2 100644
--- a/core/modules/field/theme/field.tpl.php
+++ b/core/modules/field/theme/field.tpl.php
@@ -39,7 +39,10 @@
  *   into a string within the variable $classes.
  *
  * @see template_preprocess_field()
+ * @see template_process_field()
  * @see theme_field()
+ *
+ * @ingroup themeable
  */
 ?>
 <!--