diff --git a/core/lib/Drupal/Component/Plugin/Context/ContextInterface.php b/core/lib/Drupal/Component/Plugin/Context/ContextInterface.php
index ab092ed..754b65e 100644
--- a/core/lib/Drupal/Component/Plugin/Context/ContextInterface.php
+++ b/core/lib/Drupal/Component/Plugin/Context/ContextInterface.php
@@ -8,7 +8,30 @@
 namespace Drupal\Component\Plugin\Context;
 
 /**
- * A generic context interface for wrapping data a plugin needs to operate.
+ * Interface for Drupal-specific plugin context management.
+ *
+ * Contexts are very similar to dependency injection but they have a human
+ * readable name and other features usable on the UI. Contexts must have a
+ * definition and might have a value.
+ *
+ * For example, when a block is configured to be visible on a page displaying a
+ * node of a particular type, the condition plugin needs a node to check its
+ * type. In a typical page flow, this is supplied by the routing system when
+ * on a node page but it could equally come from a views result etc. The
+ * condition plugin is implemented as a context aware plugin. The plugin
+ * context is set by
+ * \Drupal\Component\Plugin\ContextAwarePluginBase::setContext(). The
+ * $context argument passed to setContext() needs to have
+ * $this->getContextDefinition()->getDataType() == 'entity:node' as defined
+ * on the \Drupal\node\Plugin\Condition\NodeType plugin annotation otherwise
+ * the NodeType plugin will not be considered for UI or runtime purposes.
+ *
+ * When in the UI, this context is enough. However, when actually checking a
+ * block visibility then a node is required by the NodeType plugin, this is the
+ * value of the context as set by the setContextValue() on this interface. For
+ * the example above,
+ * \Drupal\block\EventSubscriber\NodeRouteContext::determineBlockContext sets
+ * the "node" context together with an appropriate value.
  */
 interface ContextInterface {
 
