diff -u b/core/modules/field/field.api.php b/core/modules/field/field.api.php
--- b/core/modules/field/field.api.php
+++ b/core/modules/field/field.api.php
@@ -712,7 +712,7 @@
  * Perform alterations on Field API widget types.
  *
  * @param array $info
- *   Array of informations on existing widget types, as collected by the
+ *   An array of informations on existing widget types, as collected by the
  *   annotation discovery mechanism.
  */
 function hook_field_widget_info_alter(array &$info) {
diff -u b/core/modules/field/lib/Drupal/field/FieldInstance.php b/core/modules/field/lib/Drupal/field/FieldInstance.php
--- b/core/modules/field/lib/Drupal/field/FieldInstance.php
+++ b/core/modules/field/lib/Drupal/field/FieldInstance.php
@@ -12,6 +12,11 @@
  */
 class FieldInstance implements \ArrayAccess {
 
+  /**
+   * The instance definition, as read from configuration storage.
+   *
+   * @var array
+   */
   public $definition;
 
   /**
diff -u b/core/modules/field/lib/Drupal/field/Plugin/Type/Widget/WidgetPluginManager.php b/core/modules/field/lib/Drupal/field/Plugin/Type/Widget/WidgetPluginManager.php
--- b/core/modules/field/lib/Drupal/field/Plugin/Type/Widget/WidgetPluginManager.php
+++ b/core/modules/field/lib/Drupal/field/Plugin/Type/Widget/WidgetPluginManager.php
@@ -17,21 +17,34 @@
  */
 class WidgetPluginManager extends PluginManagerBase {
 
+  /**
+   * Overrides Drupal\Component\Plugin\PluginManagerBase:$defaults.
+   */
   protected $defaults = array(
     'settings' => array(),
     'multiple_values' => FALSE,
   );
 
+  /**
+   * The cache bin used for plugin definitions.
+   *
+   * @var string
+   */
   protected $cache_bin = 'field';
-  protected $cache_key = 'field_widget_types';
-  protected $hook = 'field_widget_info';
+
+  /**
+   * The cache id used for plugin definitions.
+   *
+   * @var string
+   */
+  protected $cache_id = 'field_widget_types';
 
   /**
    * Constructs a WidgetPluginManager object.
    */
   public function __construct() {
     $this->baseDiscovery = new LegacyDiscoveryDecorator(new AnnotatedClassDiscovery('field', 'widget'));
-    $this->discovery = new CacheDecorator($this->baseDiscovery, $this->cache_key, $this->cache_bin);
+    $this->discovery = new CacheDecorator($this->baseDiscovery, $this->cache_id, $this->cache_bin);
 
     $this->factory = new WidgetFactory($this);
   }
@@ -43,8 +56,8 @@
    */
   public function clearDefinitions() {
     // Clear 'static' data by creating a new object.
-    $this->discovery = new CacheDecorator($this->baseDiscovery, $this->cache_key, $this->cache_bin);
-    cache($this->cache_bin)->delete($this->cache_key);
+    $this->discovery = new CacheDecorator($this->baseDiscovery, $this->cache_id, $this->cache_bin);
+    cache($this->cache_bin)->delete($this->cache_id);
   }
 
   /**