diff --git a/core/lib/Drupal/Core/TypedData/AllowedValuesInterface.php b/core/lib/Drupal/Core/TypedData/AllowedValuesInterface.php
index faa00b4..4e36ca7 100644
--- a/core/lib/Drupal/Core/TypedData/AllowedValuesInterface.php
+++ b/core/lib/Drupal/Core/TypedData/AllowedValuesInterface.php
@@ -9,15 +9,21 @@
 use Drupal\Core\Session\AccountInterface;
 
 /**
- * Interface for retrieving allowed values.
+ * Interface for retrieving allowed and possible values.
  *
- * While allowed values define the values that are allowed to be set by a user,
- * possible values specify which values existing data might have.
+ * While possible values specify which values existing data might have, allowed
+ * values define the values that are allowed to be set by a user.
  *
- * For example, in an workflow scenario the allowed options for a state field
- * might depend on the currently set state, while possible options are all
- * states. Thus allowed values would be used during any editing context, while
+ * For example, in an workflow scenario, the allowed values for a state field
+ * might depend on the currently set state, while possible values are all
+ * states. Thus allowed values would be used in an editing context, while
  * possible values would be used for presenting filtering options in a search.
+ *
+ * For convenience, lists of both allowed and possible values are also provided
+ * as structured options arrays that can be used in an Options widget such as a
+ * select box or checkboxes.
+ *
+ * @see \Drupal\options\Plugin\field\widget\OptionsWidgetBase
  */
 interface AllowedValuesInterface {
 
@@ -28,7 +34,7 @@
    *   (optional) The user account for which to generate the allowed values.
    *
    * @return array
-   *   An array allowed values.
+   *   An array of allowed values.
    */
   public function getValues(AccountInterface $account = NULL);