commit 3f80424b15b15fcf490e0606c45602454f9422e6
Author: Shane Auckland <shane.auckland@gmail.com>
Date:   Thu Apr 11 08:05:13 2013 +0100

    1786740-new_changes

diff --git a/core/modules/field/field.crud.inc b/core/modules/field/field.crud.inc
index 31a574d..aa9f1b1 100644
--- a/core/modules/field/field.crud.inc
+++ b/core/modules/field/field.crud.inc
@@ -535,15 +535,17 @@ function field_create_instance(&$instance) {
  *   - field_name: The name of an existing field.
  *   Read-only ID properties are assigned automatically. Any other properties
  *   specified in $instance overwrite the existing values for that instance of
- *   the field. Missing properties from instance are overwritten if they have
- *   defaults defined. Everything else in $instance is written as a new value.
- *   To preserve the existing field properties and make specific changes, first
- *   load the field definition with field_info_instance():
+ *   the field. Properties that are missing from $instance are overwritten on 
+ *   the field instance if they have defaults defined. Everything else in 
+ *   $instance is written as a new value. To preserve the existing field 
+ *   properties and make specific changes; first load an instance info array 
+ *   with field_info_instance(), then change the values of the instance info's
+ *   definition value and finally pass the definition array as $instance:
  *   @code
  *     $instance_info = field_info_instance($entity_type, $field_name, $bundle_name);
- *     // Change a single property
+ *     // Change a single property.
  *     $instance_info['definition']['required'] = TRUE;
- *     // Write the change back
+ *     // Write the change back.
  *     field_update_instance($instance_info['definition']);
  *   @endcode
  *