commit 63671210cf8397e3f82c53341752c60955f06598
Author: gnuget <gnuget@992990.no-reply.drupal.org>
Date:   Tue Apr 30 17:12:04 2013 -0500

    [#1898434] http://drupal.org/node/1898434#comment-7361406

diff --git a/core/modules/options/lib/Drupal/options/Plugin/field/widget/OptionsWidgetBase.php b/core/modules/options/lib/Drupal/options/Plugin/field/widget/OptionsWidgetBase.php
index 6ab1cf7..981bb61 100644
--- a/core/modules/options/lib/Drupal/options/Plugin/field/widget/OptionsWidgetBase.php
+++ b/core/modules/options/lib/Drupal/options/Plugin/field/widget/OptionsWidgetBase.php
@@ -112,8 +112,10 @@ public static function validateElement(array $element, array &$form_state) {
    */
   protected function getOptions() {
     if (!isset($this->options)) {
+      $module_handler = \Drupal::moduleHandler();
+
       // Get the list of options from the field type module, and sanitize them.
-      $options = (array) \Drupal::moduleHandler()->invoke($this->field['module'], 'options_list', array($this->field, $this->instance, $this->entity));
+      $options = (array) $module_handler->invoke($this->field['module'], 'options_list', array($this->field, $this->instance, $this->entity));
 
       // Add an empty option if the widget needs one.
       if ($empty_option = $this->getEmptyOption()) {
@@ -130,7 +132,12 @@ protected function getOptions() {
         $options = array('_none' => $label) + $options;
       }
 
-      \Drupal::moduleHandler()->alter('options_list', $options, $this->field);
+      $context = array(
+        'field' => $this->field,
+        'instance' => $this->instance,
+        'entity' => $this->entity
+      );
+      $module_handler->alter('options_list', $options, $context);
 
       array_walk_recursive($options, array($this, 'sanitizeLabel'));
 
diff --git a/core/modules/options/options.api.php b/core/modules/options/options.api.php
index 44118a9..0cba438 100644
--- a/core/modules/options/options.api.php
+++ b/core/modules/options/options.api.php
@@ -70,18 +70,29 @@ function hook_options_list($field, $instance, $entity) {
 }
 
 /**
- * Alter the options that is displayed in a option list
+ * Alters the list of options to be displayed for a field.
  *
- * Called by getOptions() to allow modules to alter the options that's
- * used in a field. Can be used to modify the label of the _none option
+ * This hook can notably be used to change the label of the '_none' option.
  *
- * @param $options
- *   An array with the options of the option list
+ * @param array $options
+ *   The array of options for the field, as returned by hook_options_list(). A 
+ *   '_none' option might have been added, depending on the field properties.
  *
- * @param $field
- *   An object with the field definition
+ * @param array $context
+ *   An array with these values:
+ *
+ * @param \Drupal\field\Plugin\Core\Entity\Field $field
+ *   The field definition.
+ * @param Drupal\field\Plugin\Core\Entity\FieldInstance $instance
+ *   The instance definition. It is recommended to only use instance level
+ *   properties to filter out values from a list defined by field level
+ *   properties.
+ * @param \Drupal\Core\Entity\EntityInterface $entity
+ *   The entity object the field is attached to.
+ *
+ * @see hook_options_list()
  */
-function hook_options_list_alter(&$options, $field) {
+function hook_options_list_alter(&$options, $context) {
   // Check if is the field where want be changed the label of the _none option
   if ($field->id == 'field_option') {
     // Change the label of the _none option