From 0790cd975bdb4b58f6da83445c51286cc06d2861 Mon Sep 17 00:00:00 2001
From: Jennifer Hodgdon <yahgrp@poplarware.com>
Date: Thu, 27 Sep 2012 08:44:17 -0700
Subject: [PATCH] Issue #1326634 by xjm, NROTC_Webmaster, dellintosh,
 xenophyle: Fix up API docs in field module

---
 core/modules/field/field.api.php              | 259 ++++++------
 core/modules/field/field.attach.inc           | 271 +++++++------
 core/modules/field/field.crud.inc             | 116 +++---
 core/modules/field/field.default.inc          |  49 ++-
 core/modules/field/field.form.inc             |  47 ++-
 core/modules/field/field.info.inc             |  87 ++--
 core/modules/field/field.install              |  16 +-
 core/modules/field/field.module               | 373 +++++++++---------
 core/modules/field/field.multilingual.inc     |  16 +-
 .../field_sql_storage.install                 |   4 +-
 .../field_sql_storage.module                  |  55 +--
 .../field/modules/number/number.install       |   2 +-
 .../field/modules/number/number.module        |   4 +-
 .../field/modules/options/options.module      |  55 ++-
 core/modules/field/modules/text/text.install  |   2 +-
 core/modules/field/modules/text/text.module   |  44 +--
 16 files changed, 782 insertions(+), 618 deletions(-)

diff --git a/core/modules/field/field.api.php b/core/modules/field/field.api.php
index e55989e01e8..a1c93de82df 100644
--- a/core/modules/field/field.api.php
+++ b/core/modules/field/field.api.php
@@ -17,16 +17,16 @@ use Drupal\field\FieldUpdateForbiddenException;
  *
  * 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:
@@ -87,7 +87,7 @@ function hook_field_extra_fields_alter(&$info) {
 /**
  * @defgroup field_types Field Types API
  * @{
- * Define field types.
+ * Defines field, widget, display formatter, and 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,
@@ -101,7 +101,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
@@ -128,10 +128,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
@@ -213,14 +213,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') {
@@ -317,8 +316,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
@@ -339,7 +338,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.
  */
@@ -383,7 +382,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) {
@@ -600,9 +599,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.
@@ -639,7 +638,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
@@ -667,8 +666,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') {
@@ -853,17 +852,17 @@ function hook_field_widget_properties_alter(array &$widget_properties, array $co
  * 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()
@@ -923,7 +922,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().
  *
@@ -932,6 +931,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
@@ -948,10 +950,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();
@@ -1010,13 +1008,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();
@@ -1082,18 +1080,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.
@@ -1128,7 +1126,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.
@@ -1145,8 +1153,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
@@ -1166,7 +1174,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.
@@ -1177,7 +1188,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.
@@ -1188,7 +1202,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.
@@ -1197,8 +1214,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
@@ -1218,7 +1235,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.
@@ -1229,7 +1249,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.
@@ -1240,8 +1263,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'.
@@ -1277,9 +1300,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) {
@@ -1310,9 +1333,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') {
@@ -1369,7 +1392,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
@@ -1382,7 +1408,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.
@@ -1431,16 +1462,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(
@@ -1473,8 +1504,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.
@@ -1539,12 +1570,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'.
@@ -1559,9 +1589,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();
@@ -1611,8 +1640,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'.
@@ -1883,8 +1912,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.
@@ -1955,13 +1984,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'.
@@ -1976,11 +2005,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.
@@ -2103,7 +2131,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
@@ -2138,7 +2166,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
@@ -2176,8 +2204,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'.
@@ -2381,11 +2409,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.
@@ -2399,11 +2427,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.
@@ -2417,8 +2445,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.
@@ -2433,9 +2461,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.
@@ -2449,8 +2476,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 86cdf02104e..2579126e4b4 100644
--- a/core/modules/field/field.attach.inc
+++ b/core/modules/field/field.attach.inc
@@ -11,7 +11,7 @@ use Drupal\Core\Entity\EntityInterface;
 /**
  * @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
@@ -31,8 +31,7 @@ use Drupal\Core\Entity\EntityInterface;
 /**
  * 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';
 
@@ -50,7 +49,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
@@ -61,18 +60,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
@@ -89,16 +88,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.
@@ -298,7 +297,7 @@ function _field_invoke($op, $entity_type, EntityInterface $entity, &$a = NULL, &
 }
 
 /**
- * Invoke a field hook across fields on multiple entities.
+ * Invokes a field hook across fields on multiple entities.
  *
  * @param $op
  *   Possible operations include:
@@ -307,9 +306,9 @@ function _field_invoke($op, $entity_type, EntityInterface $entity, &$a = NULL, &
  *   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.
@@ -317,30 +316,30 @@ function _field_invoke($op, $entity_type, EntityInterface $entity, &$a = NULL, &
  *   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.
@@ -361,7 +360,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
@@ -460,6 +459,48 @@ function _field_invoke_default($op, $entity_type, EntityInterface $entity, &$a =
  * 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()) {
@@ -468,7 +509,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.
@@ -476,7 +519,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
@@ -535,7 +578,7 @@ function _field_invoke_widget_target() {
 }
 
 /**
- * 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
@@ -672,26 +715,25 @@ function field_attach_form($entity_type, EntityInterface $entity, &$form, &$form
  * 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();
@@ -808,7 +850,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.
@@ -818,12 +860,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.
@@ -833,12 +875,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'.
@@ -869,21 +910,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'.
@@ -917,10 +958,10 @@ function field_attach_form_validate($entity_type, EntityInterface $entity, $form
 }
 
 /**
- * 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'.
@@ -947,10 +988,10 @@ function field_attach_submit($entity_type, EntityInterface $entity, $form, &$for
 }
 
 /**
- * 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'.
@@ -1019,7 +1060,7 @@ function field_attach_insert($entity_type, EntityInterface $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'.
@@ -1071,8 +1112,8 @@ function field_attach_update($entity_type, EntityInterface $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'.
@@ -1106,8 +1147,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'.
@@ -1136,24 +1177,23 @@ function field_attach_delete_revision($entity_type, $entity) {
 }
 
 /**
- * Prepare field data prior to display.
+ * 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
- * optimisation when displaying lists of entities.
+ * 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
+ * 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
@@ -1194,13 +1234,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:
@@ -1270,7 +1309,7 @@ function field_attach_view($entity_type, EntityInterface $entity, $view_mode, $l
 }
 
 /**
- * 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
@@ -1308,7 +1347,7 @@ function field_attach_preprocess($entity_type, EntityInterface $entity, $element
 /**
  * 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.
@@ -1345,7 +1384,7 @@ function field_attach_prepare_translation($entity_type, EntityInterface $entity,
 }
 
 /**
- * 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.
@@ -1364,7 +1403,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.
@@ -1394,12 +1433,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 48a97973baf..2b28a569379 100644
--- a/core/modules/field/field.crud.inc
+++ b/core/modules/field/field.crud.inc
@@ -11,13 +11,12 @@ use Drupal\Core\Entity\EntityFieldQuery;
 /**
  * @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.
@@ -301,16 +300,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.
  */
@@ -325,15 +324,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));
@@ -509,12 +508,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.
  *
@@ -650,9 +649,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.
@@ -661,11 +660,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.
  */
@@ -678,15 +677,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.
  */
@@ -777,7 +776,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
@@ -786,20 +785,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
@@ -807,8 +805,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
@@ -820,12 +818,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(
@@ -907,8 +905,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
@@ -939,7 +937,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 7d1a309c425..fa9133030fe 100644
--- a/core/modules/field/field.default.inc
+++ b/core/modules/field/field.default.inc
@@ -25,18 +25,18 @@
  * @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.
@@ -54,11 +54,24 @@ function field_default_validate($entity_type, $entity, $field, $instance, $langc
 }
 
 /**
- * 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
@@ -79,20 +92,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) {
@@ -204,15 +217,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 dae9ec92018..583072576b9 100644
--- a/core/modules/field/field.form.inc
+++ b/core/modules/field/field.form.inc
@@ -8,14 +8,15 @@
 /**
  * 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'];
@@ -82,11 +83,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()
  */
@@ -103,7 +112,7 @@ function field_form_element_after_build($element, &$form_state) {
 }
 
 /**
- * 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
@@ -129,7 +138,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.
@@ -174,12 +183,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()
@@ -213,6 +222,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
@@ -238,7 +257,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 54ab32e8923..50b270f73a7 100644
--- a/core/modules/field/field.info.inc
+++ b/core/modules/field/field.info.inc
@@ -10,11 +10,11 @@ use Drupal\field\FieldInstance;
 /**
  * @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.
@@ -23,9 +23,8 @@ use Drupal\field\FieldInstance;
 /**
  * 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');
@@ -145,7 +144,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');
@@ -158,15 +157,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()
  */
@@ -240,7 +239,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');
@@ -255,6 +254,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.
@@ -277,7 +279,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.
@@ -327,8 +329,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']);
@@ -364,6 +368,9 @@ function _field_info_prepare_instance_display($field, $display) {
  *   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);
@@ -408,8 +415,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.
  *
@@ -428,8 +435,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
@@ -502,8 +508,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();
@@ -525,9 +531,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();
@@ -549,7 +555,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();
@@ -590,13 +596,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()
  */
@@ -637,8 +643,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();
@@ -722,8 +728,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.
@@ -749,6 +755,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 9ef54d0e5ec..d665d361188 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_7000_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 ce652cf1efe..e13f386c164 100644
--- a/core/modules/field/field.module
+++ b/core/modules/field/field.module
@@ -22,166 +22,162 @@ require_once DRUPAL_ROOT . '/core/modules/field/field.form.inc';
 /**
  * @defgroup field Field API
  * @{
- * Attach custom data fields to Drupal entities.
+ * 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 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.
+ * 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'.
+ * 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:
  *     - ...
@@ -191,37 +187,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_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_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_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_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_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_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_language Field language API @endlink: Provides native
  *   multilingual support for the Field API.
  */
 
@@ -257,14 +250,16 @@ 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().
+ * Load the most recent version of an entity's field data.
+ *
+ * @see 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().
+ * Load the version of an entity's field data specified in the entity.
+ *
+ * @see field_attach_load().
  */
 const FIELD_LOAD_REVISION = 'FIELD_LOAD_REVISION';
 
@@ -335,7 +330,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) {
@@ -545,7 +540,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.
@@ -568,8 +563,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'])) {
@@ -584,8 +586,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);
@@ -594,7 +597,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);
@@ -759,7 +764,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'];
@@ -789,7 +794,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();
@@ -797,25 +802,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()) . '>';
@@ -827,7 +841,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.
@@ -835,11 +849,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.
  */
@@ -886,7 +901,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.
@@ -894,28 +909,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.
  *
@@ -991,10 +1006,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.
  */
@@ -1012,12 +1028,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().
@@ -1029,8 +1045,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;
@@ -1050,13 +1065,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.
  */
@@ -1189,8 +1205,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
@@ -1199,7 +1215,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 e3fbd2dc55a..f84b30a6f1f 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:
@@ -142,8 +148,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.
@@ -207,8 +212,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.
@@ -250,6 +255,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.
  */
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 2229ef40ad2..a4e05441e01 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 1b17d3c1e5b..310cf6ca194 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
@@ -37,12 +37,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']) {
@@ -54,12 +55,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']) {
@@ -71,40 +73,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.
@@ -227,8 +232,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']) {
@@ -633,11 +638,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);
@@ -754,8 +759,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/number/number.install b/core/modules/field/modules/number/number.install
index 02c7a305750..3c4ae7f7f17 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 1a7024b6a8b..6eb729a481c 100644
--- a/core/modules/field/modules/number/number.module
+++ b/core/modules/field/modules/number/number.module
@@ -119,8 +119,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) {
diff --git a/core/modules/field/modules/options/options.module b/core/modules/field/modules/options/options.module
index 4d70277c19e..31652e32b18 100644
--- a/core/modules/field/modules/options/options.module
+++ b/core/modules/field/modules/options/options.module
@@ -561,7 +561,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') {
@@ -575,6 +575,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(
@@ -655,9 +667,12 @@ function _options_get_options($field, $instance, $properties, $entity_type, $ent
 }
 
 /**
- * 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) {
@@ -678,6 +693,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);
@@ -694,6 +721,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']);
@@ -725,13 +758,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.
  */
@@ -790,9 +824,10 @@ function options_options_list($field, $instance, $entity_type, $entity) {
 }
 
 /**
- * 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/text/text.install b/core/modules/field/modules/text/text.install
index 1b8d00b1e6e..a2ef0cff184 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 b27021e515a..4387ff2b058 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()
  */
@@ -302,14 +302,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
@@ -321,27 +321,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.
  */