#369562 by yched: More Field API clean-ups.

14 files changed, 141 insertions, 130 deletions

diff --git a/modules/field/field.api.php b/modules/field/field.api.php
index 29381c0b4..018f4bf96 100644
--- a/modules/field/field.api.php
+++ b/modules/field/field.api.php
@@ -17,11 +17,11 @@
  *
  *   name: The human-readable name of the type.
  *   id key: The object property that contains the primary id for the
- *     object.  Every object passed to the Field API must
+ *     object. Every object passed to the Field API must
  *     have this property and its value must be numeric.
  *   revision key: The object property that contains the revision id
  *     for the object, or NULL if the object type is not
- *     versioned.  The Field API assumes that all revision ids are
+ *     versioned. The Field API assumes that all revision ids are
  *     unique across all instances of a type; this means, for example,
  *     that every object's revision ids cannot be 0, 1, 2, ...
  *   bundle key: The object property that contains the bundle name for
@@ -31,7 +31,7 @@
  *     loaded fields for each object, reducing the cost of
  *     field_attach_load().
  *   bundles: An array of all existing bundle names for this object
- *     type.  TODO: Define format.  TODO: I'm unclear why we need
+ *     type. TODO: Define format. TODO: I'm unclear why we need
  *     this.
  */
 function hook_fieldable_info() {
@@ -60,7 +60,7 @@ function hook_fieldable_info() {
  * @{
  * Define field types, widget types, and display formatter types.
  *
- * The bulk of the Field Types API are related to field types.  A
+ * The bulk of the Field Types API are related to field types. A
  * field type represents a particular data storage type (integer,
  * string, date, etc.) that can be attached to a fieldable object.
  * hook_field_info() defines the basic properties of a field type, and
@@ -68,10 +68,10 @@ function hook_fieldable_info() {
  * to perform field-type-specific actions.
  *
  * The Field Types API also defines widget types via
- * hook_field_widget_info().  Widgets are Form API elements with
- * additional processing capabilities.  A field module can define
+ * hook_field_widget_info(). Widgets are Form API elements with
+ * additional processing capabilities. A field module can define
  * widgets that work with its own field types or with any other
- * module's field types.  Widget hooks are typically called by the
+ * module's field types. Widget hooks are typically called by the
  * Field Attach API when creating the field form elements during
  * field_attach_form().
  *
@@ -119,8 +119,8 @@ function hook_field_info() {
  *   A field structure.
  * @return
  *   A Field API schema is an array of Schema API column
- *   specifications, keyed by field-independent column name.  For
- *   example, a field may declare a column named 'value'.  The SQL
+ *   specifications, keyed by field-independent column name. For
+ *   example, a field may declare a column named 'value'. The SQL
  *   storage engine may create a table with a column named
  *   <fieldname>_value_0, but the Field API schema column name is
  *   still 'value'.
@@ -214,7 +214,7 @@ function hook_field_load($obj_type, $object, $field, $instance, $items) {
  * @param $items
  *   $object->{$field['field_name']}, or an empty array if unset.
  * @param $form
- *   The form structure being validated.  NOTE: This parameter will
+ *   The form structure being validated. NOTE: This parameter will
  *   become obsolete (see field_attach_validate()).
  */
 function hook_field_validate($obj_type, $object, $field, $instance, $items, $form) {
@@ -274,7 +274,7 @@ function hook_field_update($obj_type, $object, $field, $instance, $items) {
 }
 
 /**
- * Define custom delete behavior for this module's field types.  This
+ * Define custom delete behavior for this module's field types. This
  * hook is invoked just before the data is deleted from field storage.
  *
  * @param $obj_type
@@ -293,7 +293,7 @@ function hook_field_delete($obj_type, $object, $field, $instance, $items) {
 
 /**
  * Define custom delete_revision behavior for this module's field
- * types.  This hook is invoked just before the data is deleted from
+ * types. This hook is invoked just before the data is deleted from
  * field storage, and will only be called for fieldable types that are
  * versioned.
  *
@@ -355,7 +355,7 @@ function hook_field_prepare_translation($obj_type, $object, $field, $instance, $
  * provide it with valid $field information.
  *
  * Field API will set the weight, field name and delta values for each
- * form element.  If there are multiple values for this field, the
+ * form element. If there are multiple values for this field, the
  * Field API will call this function as many times as needed.
  *
  * @param $form
@@ -393,7 +393,7 @@ function hook_field_widget(&$form, &$form_state, $field, $instance, $items, $del
  */
 
 /**
- * Act on field_attach_form.  This hook is invoked after the field module
+ * Act on field_attach_form. This hook is invoked after the field module
  * has performed the operation.
  *
  * See field_attach_form() for details and arguments.
@@ -402,17 +402,17 @@ function hook_field_attach_form($obj_type, $object, &$form, &$form_state) {
 }
 
 /**
- * Act on field_attach_load.  This hook is invoked after the field module
+ * Act on field_attach_load. This hook is invoked after the field module
  * has performed the operation.
  *
- * See field_attach_load() for details and arguments.  TODO:
+ * See field_attach_load() for details and arguments. TODO:
  * Currently, this hook only accepts a single object a time.
  */
 function hook_field_attach_load($obj_type, $object) {
 }
 
 /**
- * Act on field_attach_validate.  This hook is invoked after the field module
+ * Act on field_attach_validate. This hook is invoked after the field module
  * has performed the operation.
  *
  * See field_attach_validate() for details and arguments.
@@ -421,7 +421,7 @@ function hook_field_attach_validate($obj_type, $object, &$form) {
 }
 
 /**
- * Act on field_attach_submit.  This hook is invoked after the field module
+ * Act on field_attach_submit. This hook is invoked after the field module
  * has performed the operation.
  *
  * See field_attach_submit() for details and arguments.
@@ -430,7 +430,7 @@ function hook_field_attach_submit($obj_type, $object, $form, &$form_state) {
 }
 
 /**
- * Act on field_attach_presave.  This hook is invoked after the field module
+ * Act on field_attach_presave. This hook is invoked after the field module
  * has performed the operation.
  *
  * See field_attach_presave() for details and arguments.
@@ -439,7 +439,7 @@ function hook_field_attach_presave($obj_type, $object) {
 }
 
 /**
- * Act on field_attach_insert.  This hook is invoked after the field module
+ * Act on field_attach_insert. This hook is invoked after the field module
  * has performed the operation.
  *
  * See field_attach_insert() for details and arguments.
@@ -448,7 +448,7 @@ function hook_field_attach_insert($obj_type, $object) {
 }
 
 /**
- * Act on field_attach_update.  This hook is invoked after the field module
+ * Act on field_attach_update. This hook is invoked after the field module
  * has performed the operation.
  *
  * See field_attach_update() for details and arguments.
@@ -457,7 +457,7 @@ function hook_field_attach_update($obj_type, $object) {
 }
 
 /**
- * Act on field_attach_delete.  This hook is invoked after the field module
+ * Act on field_attach_delete. This hook is invoked after the field module
  * has performed the operation.
  *
  * See field_attach_delete() for details and arguments.
@@ -466,7 +466,7 @@ function hook_field_attach_delete($obj_type, $object) {
 }
 
 /**
- * Act on field_attach_delete_revision.  This hook is invoked after
+ * Act on field_attach_delete_revision. This hook is invoked after
  * the field module has performed the operation.
  *
  * See field_attach_delete_revision() for details and arguments.
@@ -475,7 +475,7 @@ function hook_field_attach_delete_revision($obj_type, $object) {
 }
 
 /**
- * Act on field_attach_view.  This hook is invoked after the field module
+ * Act on field_attach_view. This hook is invoked after the field module
  * has performed the operation.
  *
  * @param $output
@@ -491,7 +491,7 @@ function hook_field_attach_view($output, $obj_type, $object, $teaser) {
 }
 
 /**
- * Act on field_attach_create_bundle.  This hook is invoked after the
+ * Act on field_attach_create_bundle. This hook is invoked after the
  * field module has performed the operation.
  *
  * See field_attach_create_bundle() for details and arguments.
@@ -500,7 +500,7 @@ function hook_field_attach_create_bundle($bundle) {
 }
 
 /**
- * Act on field_attach_rename_bundle.  This hook is invoked after the
+ * Act on field_attach_rename_bundle. This hook is invoked after the
  * field module has performed the operation.
  *
  * See field_attach_rename_bundle() for details and arguments.
@@ -509,7 +509,7 @@ function hook_field_rename_bundle($bundle_old, $bundle_new) {
 }
 
 /**
- * Act on field_attach_delete_bundle.  This hook is invoked after the field module
+ * Act on field_attach_delete_bundle. This hook is invoked after the field module
  * has performed the operation.
  *
  * See field_attach_delete_bundle() for details and arguments.
@@ -580,7 +580,7 @@ function hook_field_storage_delete($obj_type, $object) {
  * @param $obj_type
  *   The entity type of object, such as 'node' or 'user'.
  * @param $object
- *   The object on which to operate.  The revision to delete is
+ *   The object on which to operate. The revision to delete is
  *   indicated by the object's revision id property, as identified by
  *   hook_fieldable_info() for $obj_type.
  */
@@ -650,7 +650,7 @@ function hook_field_storage_delete_instance($field_name, $bundle) {
  */
 
 /**
- * Act on a field being created.  This hook is invoked after the field
+ * Act on a field being created. This hook is invoked after the field
  * is created and so it cannot modify the field itself.
  *
  * TODO: Not implemented.
@@ -662,7 +662,7 @@ function hook_field_create_field($field) {
 }
 
 /**
- * Act on a field instance being created.  This hook is invoked after
+ * Act on a field instance being created. This hook is invoked after
  * the instance record is saved and so it cannot modify the instance
  * itself.
  *
@@ -673,7 +673,7 @@ function hook_field_create_instance($instance) {
 }
 
 /**
- * Act on a field being deleted.  This hook is invoked just before the
+ * Act on a field being deleted. This hook is invoked just before the
  * field is deleted.
  *
  * TODO: Not implemented.
@@ -686,7 +686,7 @@ function hook_field_delete_field($field) {
 
 
 /**
- * Act on a field instance being updated.  This hook is invoked after
+ * Act on a field instance being updated. This hook is invoked after
  * the instance record is saved and so it cannot modify the instance
  * itself.
  *
@@ -699,7 +699,7 @@ function hook_field_update_instance($instance) {
 }
 
 /**
- * Act on a field instance being deleted.  This hook is invoked just
+ * Act on a field instance being deleted. This hook is invoked just
  * before the instance is deleted.
  *
  * TODO: Not implemented.
diff --git a/modules/field/field.attach.inc b/modules/field/field.attach.inc
index b16f174e3..825c9571f 100644
--- a/modules/field/field.attach.inc
+++ b/modules/field/field.attach.inc
@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Field attach API, allowing objects (nodes, users, ...) to be 'fieldable'.
+ */
+
 // TODO D7 : consistency - do field_attach_functions return a value or alter in place ?
 
 // TOTO D7 : consistency - some of these functions process individual fields
@@ -13,8 +18,8 @@
  * Implement 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 operation such as read, write, or delete.  The
+ * "database access". Each Field Storage API hook function defines a
+ * primitive database operation such as read, write, or delete. The
  * default field storage module, field_sql_storage.module, uses the
  * local SQL database to implement these operations, but alternative
  * field storage engines can choose to represent the data in SQL
@@ -44,19 +49,19 @@
  * Field Attach API functions generally take $obj_type and $object
  * arguments along with additional function-specific arguments.
  * $obj_type is the type of the fieldable entity, such as 'node' or
- * 'user', and $object is the object itself.  An individual object's
+ * 'user', and $object is the object itself. An individual object's
  * bundle, if any, is read from the object's bundle key property
  * identified by hook_fieldable_info() for $obj_type.
  *
  * Fieldable types call Field Attach API functions during their own
- * API calls; for example, node_load() calls field_attach_load().  A
+ * API calls; for example, node_load() calls field_attach_load(). A
  * fieldable type may is not required to use all of the Field Attach
  * API functions.
  *
  * Most Field Attach API functions define a corresponding hook
  * function that allows any module to act on Field Attach operations
  * for any object, and access or modify all the field, form, or
- * display data for that object and operation.  These all-module hooks
+ * display data for that object and operation. These all-module hooks
  * are distinct from those of the Field Types API, such as
  * hook_field_load(), that are only invoked for the module that
  * defines a specific field type.
@@ -186,13 +191,13 @@ function _field_attach_form($obj_type, $object, &$form, $form_state) {
  *   The type of objects for which to load fields; e.g. 'node' or
  *   'user'.
  * @param $objects
- *   An array of objects for which to load fields.  The keys for
+ *   An array of objects for which to load fields. The keys for
  *   primary id and bundle name to load are identified by
  *   hook_fieldable_info for $obj_type.
  * @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 object.  Defaults to FIELD_LOAD_CURRENT; use
+ *   each object. Defaults to FIELD_LOAD_CURRENT; use
  *   field_attach_load_revision() instead of passing FIELD_LOAD_REVISION.
  * @returns
  *   On return, the objects in $objects are modified by having the
@@ -274,7 +279,7 @@ function _field_attach_load($obj_type, $objects, $age = FIELD_LOAD_CURRENT) {
  *   The type of objects for which to load fields; e.g. 'node' or
  *   'user'.
  * @param $objects
- *   An array of objects for which to load fields.  The keys for
+ *   An array of objects for which to load fields. The keys for
  *   primary id, revision id, and bundle name to load are identified by
  *   hook_fieldable_info for $obj_type.
  * @returns
@@ -292,10 +297,10 @@ function _field_attach_load_revision($obj_type, $objects) {
  *
  * NOTE: This functionality does not yet exist in its final state.
  * Eventually, field validation will occur during field_attach_insert
- * or _update which will throw an exception on failure.  For now,
+ * or _update which will throw an exception on failure. For now,
  * fieldable entities must call this during their Form API validation
  * phase, and field validation will call form_set_error for any
- * errors.  See http://groups.drupal.org/node/18019.
+ * errors. See http://groups.drupal.org/node/18019.
  *
  * @param $obj_type
  *   The type of $object; e.g. 'node' or 'user'.
@@ -364,7 +369,7 @@ function _field_attach_presave($obj_type, &$object) {
 }
 
 /**
- * Save field data for a new object.  The passed in object must
+ * Save field data for a new object. The passed in object must
  * already contain its id and (if applicable) revision id attributes.
  *
  * @param $obj_type
@@ -415,7 +420,7 @@ function _field_attach_update($obj_type, &$object) {
 }
 
 /**
- * Delete field data for an existing object.  This deletes all
+ * Delete field data for an existing object. This deletes all
  * revisions of field data for the object.
  *
  * @param $obj_type
@@ -440,7 +445,7 @@ function _field_attach_delete($obj_type, &$object) {
 }
 
 /**
- * Delete field data for a single revision of an existing object.  The
+ * Delete field data for a single revision of an existing object. The
  * passed object must have a revision id attribute.
  *
  * @param $obj_type
@@ -466,7 +471,7 @@ function _field_attach_delete_revision($obj_type, &$object) {
 
 /**
  * Generate and return a structured content array tree suitable for
- * drupal_render() for all of the fields on an object.  The format of
+ * drupal_render() for all of the fields on an object. The format of
  * each field's rendered content depends on the display formatter and
  * its settings.
  *
@@ -575,7 +580,7 @@ function _field_attach_rename_bundle($bundle_old, $bundle_new) {
  * Notify 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
+ * 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
  * (particularly since for some field types, the deletion is more than just a
@@ -600,7 +605,7 @@ function _field_attach_delete_bundle($bundle) {
 
 /**
  * Helper function to extract id, vid, and bundle name from an object.
- * 
+ *
  * @param $obj_type
  *   The type of $object; e.g. 'node' or 'user'.
  * @param $object
diff --git a/modules/field/field.autoload.inc b/modules/field/field.autoload.inc
index ee2d3552c..cce62e688 100644
--- a/modules/field/field.autoload.inc
+++ b/modules/field/field.autoload.inc
@@ -44,13 +44,13 @@ function field_attach_form($obj_type, $object, &$form, $form_state) {
  *   The type of objects for which to load fields; e.g. 'node' or
  *   'user'.
  * @param $objects
- *   An array of objects for which to load fields.  The keys for
+ *   An array of objects for which to load fields. The keys for
  *   primary id and bundle name to load are identified by
  *   hook_fieldable_info for $obj_type.
  * @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 object.  Defaults to FIELD_LOAD_CURRENT; use
+ *   each object. Defaults to FIELD_LOAD_CURRENT; use
  *   field_attach_load_revision() instead of passing FIELD_LOAD_REVISION.
  * @returns
  *   On return, the objects in $objects are modified by having the
@@ -71,7 +71,7 @@ function field_attach_load($obj_type, $objects, $age = FIELD_LOAD_CURRENT) {
  *   The type of objects for which to load fields; e.g. 'node' or
  *   'user'.
  * @param $objects
- *   An array of objects for which to load fields.  The keys for
+ *   An array of objects for which to load fields. The keys for
  *   primary id, revision id, and bundle name to load are identified by
  *   hook_fieldable_info for $obj_type.
  * @returns
@@ -92,10 +92,10 @@ function field_attach_load_revision($obj_type, $objects) {
  *
  * NOTE: This functionality does not yet exist in its final state.
  * Eventually, field validation will occur during field_attach_insert
- * or _update which will throw an exception on failure.  For now,
+ * or _update which will throw an exception on failure. For now,
  * fieldable entities must call this during their Form API validation
  * phase, and field validation will call form_set_error for any
- * errors.  See http://groups.drupal.org/node/18019.
+ * errors. See http://groups.drupal.org/node/18019.
  *
  * @param $obj_type
  *   The type of $object; e.g. 'node' or 'user'.
@@ -152,7 +152,7 @@ function field_attach_presave($obj_type, &$object) {
 }
 
 /**
- * Save field data for a new object.  The passed in object must
+ * Save field data for a new object. The passed in object must
  * already contain its id and (if applicable) revision id attributes.
  *
  * @param $obj_type
@@ -183,7 +183,7 @@ function field_attach_update($obj_type, &$object) {
 }
 
 /**
- * Delete field data for an existing object.  This deletes all
+ * Delete field data for an existing object. This deletes all
  * revisions of field data for the object.
  *
  * @param $obj_type
@@ -199,7 +199,7 @@ function field_attach_delete($obj_type, &$object) {
 }
 
 /**
- * Delete field data for a single revision of an existing object.  The
+ * Delete field data for a single revision of an existing object. The
  * passed object must have a revision id attribute.
  *
  * @param $obj_type
@@ -216,7 +216,7 @@ function field_attach_delete_revision($obj_type, &$object) {
 
 /**
  * Generate and return a structured content array tree suitable for
- * drupal_render() for all of the fields on an object.  The format of
+ * drupal_render() for all of the fields on an object. The format of
  * each field's rendered content depends on the display formatter and
  * its settings.
  *
@@ -297,7 +297,7 @@ function field_attach_rename_bundle($bundle_old, $bundle_new) {
  * Notify 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
+ * 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
  * (particularly since for some field types, the deletion is more than just a
@@ -315,7 +315,7 @@ function field_attach_delete_bundle($bundle) {
 
 /**
  * Helper function to extract id, vid, and bundle name from an object.
- * 
+ *
  * @param $obj_type
  *   The type of $object; e.g. 'node' or 'user'.
  * @param $object
diff --git a/modules/field/field.crud.inc b/modules/field/field.crud.inc
index 6a2a8c1cc..f994ce35a 100644
--- a/modules/field/field.crud.inc
+++ b/modules/field/field.crud.inc
@@ -3,7 +3,7 @@
 
 /**
  * @file
- * TODO: Fill me in.
+ * Field CRUD API, handling field and field instance creation and deletion.
  */
 
 /**
@@ -17,36 +17,36 @@ class FieldException extends Exception {}
  * Represent Field API fields and instances.
  *
  * 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 objects.  A Field
- * Instance is a Field attached to a single Bundle.  A Bundle is a set
+ * Instance, and the concept of a Bundle. A Field defines a
+ * particular type of data that can be attached to objects. 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.
  *
  * For example, suppose a site administrator wants Article nodes to
- * have a subtitle and photo.  Using the Field API or some UI module,
+ * have a subtitle and photo. Using the Field API or some UI module,
  * the administrator creates a field named 'subtitle' of type 'text'
- * and a field named 'photo' of type 'image'.  The administrator
+ * 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 bundle 'article' and one attaching the field
- * 'photo' to the bundle 'article'.  When the node system uses the
+ * 'photo' to the bundle 'article'. When the node system uses the
  * Field Attach API to load all fields for an Article node, it passes
  * the node's 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 bundle 'article'.
  *
  * Field objects are (currently) represented as an array of key/value
- * pairs.  The object properties are:
+ * pairs. The object properties are:
  *
  * @param array $field:
  * - field_name (string)
- *     The name of the field.  Each field name is unique within Field API.
+ *     The name of the field. Each field name is unique within Field API.
  *     When a field is attached to an object, the field's data is stored
  *     in $object->$field_name.
  * - type (string)
- *     The type of the field, such as 'text' or 'image'.  Field types
+ *     The type of the field, such as 'text' or 'image'. Field types
  *     are defined by modules that implement hook_field_into().
  * - cardinality (integer)
- *     The number of values the field can hold.  Legal values are any
+ *     The number of values the field can hold. Legal values are any
  *     positive integer or FIELD_CARDINALITY_UNLIMITED.
  * - locked (integer)
  *     TODO: undefined.
@@ -56,23 +56,23 @@ class FieldException extends Exception {}
  *     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 otherwise.  Deleted
+ *     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
+ *     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.
  * - settings (array)
- *     A sub-array of key/value pairs of field-type-specific settings.  Each
+ *     A sub-array of key/value pairs of field-type-specific settings. Each
  *     field type module defines and documents its own field settings.
  *
  * Field Instance objects are (currently) represented as an array of
- * key/value pairs.  The object properties are:
+ * key/value pairs. The object properties are:
  *
  * @param array $instance:
  * - field_name (string)
@@ -81,15 +81,15 @@ class FieldException extends Exception {}
  *     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
+ *     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
+ *     bundle. For example, the description will be the help text of
  *     Form API elements for this instance.
  * - weight (float)
  *     The order in which the field should be sorted relative
- *     to other fields when used with this bundle.  The weight affects
+ *     to other fields when used with this bundle. The weight affects
  *     ordering in both forms (see field_attach_form()) and rendered output
  *     (see field_attach_view()).
  *     TODO - this should probably become a context setting so that
@@ -97,7 +97,7 @@ class FieldException extends Exception {}
  *     contexts.
  * - required (integer)
  *     TRUE if a value for this field is required when used with this
- *     bundle, FALSE otherwise.  Currently, required-ness is only enforced
+ *     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)
@@ -109,13 +109,13 @@ class FieldException extends Exception {}
  *     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
+ *     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 types
+ *         The type of the widget, such as text_textfield. Widget types
  *         are defined by modules that implement hook_field_widget_info().
  *     - module (string, read-only)
  *         The name of the module that implements the widget type.
@@ -153,18 +153,18 @@ class FieldException extends Exception {}
  * Create, update, and delete 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.
+ * data structures. UI modules will use it to create a user interface.
  *
  * The Field CRUD API uses
  * @link field_structs Field API data structures @endlink.
  */
 
 /**
- * Create a field.  This function does not bind the field to any
+ * Create a field. This function does not bind the field to any
  * bundle; use field_create_instance for that.
  *
  * @param $field
- *   A field structure.  The field_name and type properties are required.
+ *   A field structure. The field_name and type properties are required.
  * @throw
  *   FieldException
  */
@@ -217,7 +217,7 @@ function field_create_field($field) {
 }
 
 /**
- * Read a single field record directly from the database.  Generally,
+ * Read a single field record directly from the database. Generally,
  * you should use the field_info_field() instead.
  *
  * @param $field_name
@@ -309,7 +309,7 @@ function field_delete_field($field_name) {
  * Creates an instance of a field, binding it to a bundle.
  *
  * @param $instance
- *   A field instance structure.  The field_name and bundle properties
+ *   A field instance structure. The field_name and bundle properties
  *   are required.
  * @throw
  *   FieldException
@@ -351,8 +351,8 @@ function field_create_instance($instance) {
  * @param $instance
  *   An associative array represeting an instance structure. The required
  *   keys and values are:
- *     field_name:  The name of an existing field.
- *     bundle:  The bundle this field belongs to.
+ *     field_name: The name of an existing field.
+ *     bundle: The bundle this field belongs to.
  *   Any other properties specified in $instance overwrite the
  *   existing values for the instance.
  * @throw
@@ -461,7 +461,7 @@ function _field_write_instance($instance, $update = FALSE) {
 }
 
 /**
- * Read a single instance record directly from the database.  Generally,
+ * Read a single instance record directly from the database. Generally,
  * you should use the field_info_instance() instead.
  *
  * @param $field_name
@@ -488,7 +488,7 @@ function field_read_instance($field_name, $bundle, $include_additional = array()
  * @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.
+ *   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 are inactive or have been marked deleted. Setting
diff --git a/modules/field/field.form.inc b/modules/field/field.form.inc
index dff18fb2c..df3d278a4 100644
--- a/modules/field/field.form.inc
+++ b/modules/field/field.form.inc
@@ -1,6 +1,11 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Field forms management.
+ */
+
 // TODO : merge with field.default.inc ?
 
 /**
diff --git a/modules/field/field.info.inc b/modules/field/field.info.inc
index e619e0488..52ec413dd 100644
--- a/modules/field/field.info.inc
+++ b/modules/field/field.info.inc
@@ -3,7 +3,7 @@
 
 /**
  * @file
- * TODO: Fill me in.
+ * Field Info API, providing information about available fields and field types.
  */
 
 /**
@@ -408,7 +408,6 @@ function _field_info_field($field_name) {
   }
 }
 
-
 /**
  * Return an array of instance data for a given bundle,
  * or for all known bundles, keyed by bundle name and field name.
diff --git a/modules/field/field.install b/modules/field/field.install
index d693c2ee8..23aba3167 100644
--- a/modules/field/field.install
+++ b/modules/field/field.install
@@ -1,5 +1,6 @@
 <?php
 // $Id$
+
 /**
  * Implementation of hook_install().
  */
@@ -7,7 +8,6 @@ function field_install() {
   drupal_install_schema('field');
 }
 
-
 /**
  * Implementation of hook_uninstall().
  */
diff --git a/modules/field/field.module b/modules/field/field.module
index b559db900..55489c055 100644
--- a/modules/field/field.module
+++ b/modules/field/field.module
@@ -2,7 +2,7 @@
 // $Id$
 /**
  * @file
- * Allows administrators to associate custom fields to field types.
+ * Attach custom data fields to Drupal objects.
  */
 
 /**
@@ -12,38 +12,38 @@
  *
  * The Field API allows custom data fields to be attached to Drupal
  * objects and takes care of storing, loading, editing, and rendering
- * field data.  Any object type (node, user, etc.) can use the Field
+ * field data. Any object 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
+ * 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.
  *
  * - @link field_structs Data structures: Field, Instance, Bundle @endlink.
  *
- * - @link field_types Field Types API @endlink.  Defines field types,
- *   widget types, and display formatters.  Field modules use this API
+ * - @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
+ * - @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.  The Content Construction Kit
+ *   custom data structures. The Content Construction Kit
  *   user-interface module uses this API for its major functionality.
  *
- * - @link field_attach Field Attach API @endlink.  Connects object
- *   types to the Field API.  Field Attach API functions load, store,
+ * - @link field_attach Field Attach API @endlink. Connects object
+ *   types to the Field API. Field Attach API functions load, store,
  *   generate Form API structures, display, and perform a vareity of
  *   other functions for field data connected to individual objects.
  *   Fieldable object types like node and user use this API to make
  *   themselves fieldable.
  *
- * - @link field_info Field Info API @endlink.  Exposes information
+ * - @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
+ * - @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.
  */
@@ -101,7 +101,7 @@ function field_help($path, $arg) {
  * Implementation of hook_init().
  *
  * TODO D7: Determine which functions need to always be "loaded", and
- * put autoloaders for them into field.autoload.inc.  Also figure out
+ * put autoloaders for them into field.autoload.inc. Also figure out
  * how to make this work during installation.
  */
 function field_init() {
diff --git a/modules/field/field.test b/modules/field/field.test
index 87a4b74f8..01efcecd4 100644
--- a/modules/field/field.test
+++ b/modules/field/field.test
@@ -150,7 +150,7 @@ class FieldAttachTestCase extends DrupalWebTestCase {
     // We make sure each value is stored correctly, then unset it.
     // When an entire revision's values are unset (remembering that we
     // put one extra value in $values per revision), unset the entire
-    // revision.  Then, if $rev_values is empty at the end, all
+    // revision. Then, if $rev_values is empty at the end, all
     // revision data was found.
     $results = db_select($this->revision_table, 't')->fields('t')->execute();
     foreach ($results as $row) {
@@ -180,7 +180,7 @@ class FieldAttachTestCase extends DrupalWebTestCase {
     $this->assertEqual(count($rows), 0, t("Update with an empty field_name entry empties the field."));
   }
 
-  // Test insert and update with missing or invalid fields.  For the
+  // Test insert and update with missing or invalid fields. For the
   // most part, these tests pass by not crashing or causing exceptions.
   function testFieldAttachSaveMissingData() {
     $entity_type = 'test_entity';
@@ -203,13 +203,13 @@ class FieldAttachTestCase extends DrupalWebTestCase {
     $count = db_result(db_query("SELECT COUNT(*) FROM {{$this->table}}"));
     $this->assertEqual($count, 1, 'Field data saved');
 
-    // Update: Field is missing.  Data should survive.
+    // Update: Field is missing. Data should survive.
     unset($entity->{$this->field_name});
     field_attach_update($entity_type, $entity);
     $count = db_result(db_query("SELECT COUNT(*) FROM {{$this->table}}"));
     $this->assertEqual($count, 1, 'Missing field leaves data in table');
 
-    // Update: Field is NULL  Data should be wiped.
+    // Update: Field is NULL. Data should be wiped.
     $entity->{$this->field_name} = NULL;
     field_attach_update($entity_type, $entity);
     $count = db_result(db_query("SELECT COUNT(*) FROM {{$this->table}}"));
@@ -516,8 +516,8 @@ class FieldAttachTestCase extends DrupalWebTestCase {
   }
 
   // Verify that field_attach_validate() invokes the correct
-  // hook_field_validate.  NOTE: This tests the FAPI-connected
-  // behavior of hook_field_validate.  As discussed at
+  // hook_field_validate. NOTE: This tests the FAPI-connected
+  // behavior of hook_field_validate. As discussed at
   // http://groups.drupal.org/node/18019, field validation will
   // eventually be disconnected from FAPI, at which point this
   // function will have to be rewritten.
@@ -550,7 +550,7 @@ class FieldAttachTestCase extends DrupalWebTestCase {
     $this->assertEqual(count($errors), 0, 'No extraneous form errors set');
   }
 
-  // Validate that FAPI elements are generated.  This could be much
+  // Validate that FAPI elements are generated. This could be much
   // more thorough, but it does verify that the correct widgets show up.
   function testFieldAttachForm() {
     $entity_type = 'test_entity';
diff --git a/modules/field/modules/field_sql_storage/field_sql_storage.install b/modules/field/modules/field_sql_storage/field_sql_storage.install
index 7c57dc1cb..ddd83c36d 100644
--- a/modules/field/modules/field_sql_storage/field_sql_storage.install
+++ b/modules/field/modules/field_sql_storage/field_sql_storage.install
@@ -8,7 +8,6 @@ function field_sql_storage_install() {
   drupal_install_schema('field_sql_storage');
 }
 
-
 /**
  * Implementation of hook_uninstall().
  */
@@ -16,7 +15,9 @@ function field_sql_storage_uninstall() {
   drupal_uninstall_schema('field_sql_storage');
 }
 
-
+/**
+ * Implementation of hook_schema().
+ */
 function field_sql_storage_schema() {
   $schema = array();
 
diff --git a/modules/field/modules/field_sql_storage/field_sql_storage.module b/modules/field/modules/field_sql_storage/field_sql_storage.module
index dcca1aa55..ee17c62a7 100644
--- a/modules/field/modules/field_sql_storage/field_sql_storage.module
+++ b/modules/field/modules/field_sql_storage/field_sql_storage.module
@@ -76,9 +76,9 @@ function _field_sql_storage_etid($obj_type) {
 }
 
 /**
- * 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 $field['columns'] empty to get only the
+ * 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 $field['columns'] empty to get only the
  * base schema.
  *
  * @param $field
@@ -138,7 +138,7 @@ function _field_sql_storage_schema($field) {
     $current['fields'][_field_sql_storage_columnname($field['field_name'], $column_name)] = $attributes;
   }
 
-  // Construct the revision table.  The primary key includes
+  // Construct the revision table. The primary key includes
   // revision_id but not entity_id so that multiple revision loads can
   // use the IN operator.
   $revision = $current;
@@ -298,7 +298,7 @@ function field_sql_storage_field_storage_write($obj_type, $object, $update = FAL
 }
 
 /**
- * Delete all field data for a single object.  This function actually
+ * Delete all field data for a single object. This function actually
  * deletes the data from the database.
  *
  * @param $obj_type
@@ -330,7 +330,7 @@ function field_sql_storage_field_storage_delete($obj_type, $object) {
 /**
  * Delete field data for a single revision of a single object.
  * Deleting the current (most recently written) revision is not
- * allowed as has undefined results.  This function actually deletes
+ * allowed as has undefined results. This function actually deletes
  * the data from the database.
  *
  * @param $obj_type
diff --git a/modules/field/modules/number/number.module b/modules/field/modules/number/number.module
index 2b3cdcac0..cd213d065 100644
--- a/modules/field/modules/number/number.module
+++ b/modules/field/modules/number/number.module
@@ -243,7 +243,7 @@ function number_elements() {
  * $field information.
  *
  * Field module will set the weight, field name and delta values
- * for each form element. 
+ * for each form element.
  *
  * If there are multiple values for this field, the Field module will
  * call this function as many times as needed.
@@ -418,7 +418,7 @@ function number_decimal_validate($element, &$form_state) {
  * Override this theme to make custom changes to the output.
  *
  * $element['#field_name'] contains the field name
- * $element['#delta]  is the position of this element in the group
+ * $element['#delta] is the position of this element in the group
  */
 function theme_number($element) {
   return $element['#children'];
diff --git a/modules/field/modules/options/options.module b/modules/field/modules/options/options.module
index a88c431eb..776035c64 100644
--- a/modules/field/modules/options/options.module
+++ b/modules/field/modules/options/options.module
@@ -5,6 +5,7 @@
  * @file
  * Defines selection, check box and radio button widgets for text and numeric fields.
  */
+
 /**
  * Implementation of hook_theme().
  */
@@ -128,7 +129,7 @@ function options_buttons_process($element, $edit, &$form_state, $form) {
   }
   $options = options_options($field, $instance);
   $multiple = isset($element['#multiple']) ? $element['#multiple'] : $field['cardinality'] > 1 || $field['cardinality'] == FIELD_CARDINALITY_UNLIMITED;
-  
+
   $value = array();
   foreach ($element['#value'][$field_key] as $key) {
     // Multiple (checkboxes) need the default value in the form of an array.
@@ -151,7 +152,7 @@ function options_buttons_process($element, $edit, &$form_state, $form) {
     '#options' => $options,
     '#default_value' => $value,
   );
- 
+
   // Set #element_validate in a way that it will not wipe out other
   // validation functions already set by other modules.
   if (empty($element['#element_validate'])) {
@@ -194,7 +195,7 @@ function options_select_process($element, $edit, &$form_state, $form) {
     '#options' => $options,
     '#default_value' => isset($element['#value'][$field_key]) ? $element['#value'][$field_key] : NULL,
   );
-  
+
   // Set #element_validate in a way that it will not wipe out other
   // validation functions already set by other modules.
   if (empty($element['#element_validate'])) {
@@ -407,7 +408,7 @@ function theme_options_none($instance) {
  * make custom changes to the output.
  *
  * $element['#field_name'] contains the field name
- * $element['#delta]  is the position of this element in the group
+ * $element['#delta] is the position of this element in the group
  */
 function theme_options_select($element) {
   return $element['#children'];
diff --git a/modules/field/modules/text/text.module b/modules/field/modules/text/text.module
index 7cd127bbd..69fb41913 100644
--- a/modules/field/modules/text/text.module
+++ b/modules/field/modules/text/text.module
@@ -251,7 +251,7 @@ function text_elements() {
  * $field information.
  *
  * Field module will set the weight, field name and delta values
- * for each form element. 
+ * for each form element.
  *
  * If there are multiple values for this field, the field module will
  * call this function as many times as needed.
@@ -389,7 +389,7 @@ function text_textarea_process($element, $edit, $form_state, $form) {
  * make custom changes to the output.
  *
  * $element['#field_name'] contains the field name
- * $element['#delta]  is the position of this element in the group
+ * $element['#delta] is the position of this element in the group
  */
 function theme_text_textfield($element) {
   return $element['#children'];