From 233c9ea57e24c7951e14291d1c3f9abb7d6e58fe Mon Sep 17 00:00:00 2001
From: Alex Pott <alex.a.pott@googlemail.com>
Date: Fri, 3 Jul 2015 23:58:07 +0100
Subject: [PATCH] Issue #2443323 by Wim Leers, Nitesh Sethia, yched, Fabianx,
 jhodgdon: New convention: CacheContextInterface implementations should
 mention their ID in their class-level docblock

---
 .../Core/Cache/Context/AccountPermissionsCacheContext.php   | 2 ++
 core/lib/Drupal/Core/Cache/Context/CookiesCacheContext.php  | 4 ++++
 core/lib/Drupal/Core/Cache/Context/HeadersCacheContext.php  | 4 ++++
 core/lib/Drupal/Core/Cache/Context/IpCacheContext.php       | 2 ++
 .../Drupal/Core/Cache/Context/IsSuperUserCacheContext.php   | 2 ++
 core/lib/Drupal/Core/Cache/Context/PagersCacheContext.php   | 4 ++++
 .../lib/Drupal/Core/Cache/Context/QueryArgsCacheContext.php | 6 +++---
 .../Drupal/Core/Cache/Context/RequestFormatCacheContext.php | 2 ++
 core/lib/Drupal/Core/Cache/Context/RouteCacheContext.php    | 2 ++
 .../lib/Drupal/Core/Cache/Context/RouteNameCacheContext.php | 2 ++
 core/lib/Drupal/Core/Cache/Context/SiteCacheContext.php     | 2 ++
 core/lib/Drupal/Core/Cache/Context/ThemeCacheContext.php    | 2 ++
 core/lib/Drupal/Core/Cache/Context/TimeZoneCacheContext.php | 2 ++
 core/lib/Drupal/Core/Cache/Context/UrlCacheContext.php      | 2 ++
 core/lib/Drupal/Core/Cache/Context/UserCacheContext.php     | 2 ++
 .../lib/Drupal/Core/Cache/Context/UserRolesCacheContext.php | 4 ++++
 core/modules/book/src/Cache/BookNavigationCacheContext.php  | 2 ++
 .../modules/node/src/Cache/NodeAccessGrantsCacheContext.php | 4 ++++
 .../src/Cache/EntityTestViewGrantsCacheContext.php          | 2 ++
 .../views_test_data/src/Cache/ViewsTestCacheContext.php     | 2 ++
 20 files changed, 51 insertions(+), 3 deletions(-)

diff --git a/core/lib/Drupal/Core/Cache/Context/AccountPermissionsCacheContext.php b/core/lib/Drupal/Core/Cache/Context/AccountPermissionsCacheContext.php
index 5993424ae9a4..01e6ce8ab725 100644
--- a/core/lib/Drupal/Core/Cache/Context/AccountPermissionsCacheContext.php
+++ b/core/lib/Drupal/Core/Cache/Context/AccountPermissionsCacheContext.php
@@ -12,6 +12,8 @@
 
 /**
  * Defines the AccountPermissionsCacheContext service, for "per permission" caching.
+ *
+ * Cache context ID: 'user.permissions'.
  */
 class AccountPermissionsCacheContext extends UserCacheContext {
 
diff --git a/core/lib/Drupal/Core/Cache/Context/CookiesCacheContext.php b/core/lib/Drupal/Core/Cache/Context/CookiesCacheContext.php
index e7850b8c8cbc..534d10c778aa 100644
--- a/core/lib/Drupal/Core/Cache/Context/CookiesCacheContext.php
+++ b/core/lib/Drupal/Core/Cache/Context/CookiesCacheContext.php
@@ -9,6 +9,10 @@
 
 /**
  * Defines the CookiesCacheContext service, for "per cookie" caching.
+ *
+ * Cache context ID: 'cookies' (to vary by all cookies).
+ * Calculated cache context ID: 'cookies:%name', e.g. 'cookies:device_type' (to
+ * vary by the 'device_type' cookie).
  */
 class CookiesCacheContext extends RequestStackCacheContextBase implements CalculatedCacheContextInterface {
 
diff --git a/core/lib/Drupal/Core/Cache/Context/HeadersCacheContext.php b/core/lib/Drupal/Core/Cache/Context/HeadersCacheContext.php
index 1644aa09c842..8286b362d31e 100644
--- a/core/lib/Drupal/Core/Cache/Context/HeadersCacheContext.php
+++ b/core/lib/Drupal/Core/Cache/Context/HeadersCacheContext.php
@@ -9,6 +9,10 @@
 
 /**
  * Defines the HeadersCacheContext service, for "per header" caching.
+ *
+ * Cache context ID: 'headers' (to vary by all headers).
+ * Calculated cache context ID: 'headers:%name', e.g. 'headers:X-Something' (to
+ * vary by the 'X-Something' header).
  */
 class HeadersCacheContext extends RequestStackCacheContextBase implements CalculatedCacheContextInterface {
 
diff --git a/core/lib/Drupal/Core/Cache/Context/IpCacheContext.php b/core/lib/Drupal/Core/Cache/Context/IpCacheContext.php
index 4841482f6bae..9cc6713986e6 100644
--- a/core/lib/Drupal/Core/Cache/Context/IpCacheContext.php
+++ b/core/lib/Drupal/Core/Cache/Context/IpCacheContext.php
@@ -9,6 +9,8 @@
 
 /**
  * Defines the IpCacheContext service, for "per IP address" caching.
+ *
+ * Cache context ID: 'ip'.
  */
 class IpCacheContext extends RequestStackCacheContextBase {
 
diff --git a/core/lib/Drupal/Core/Cache/Context/IsSuperUserCacheContext.php b/core/lib/Drupal/Core/Cache/Context/IsSuperUserCacheContext.php
index 3f27059638d0..1f30cf1562a9 100644
--- a/core/lib/Drupal/Core/Cache/Context/IsSuperUserCacheContext.php
+++ b/core/lib/Drupal/Core/Cache/Context/IsSuperUserCacheContext.php
@@ -9,6 +9,8 @@
 
 /**
  * Defines the IsSuperUserCacheContext service, for "super user or not" caching.
+ *
+ * Cache context ID: 'user.is_super_user'.
  */
 class IsSuperUserCacheContext extends UserCacheContext {
 
diff --git a/core/lib/Drupal/Core/Cache/Context/PagersCacheContext.php b/core/lib/Drupal/Core/Cache/Context/PagersCacheContext.php
index 23bdb7c99dc5..f53d46457216 100644
--- a/core/lib/Drupal/Core/Cache/Context/PagersCacheContext.php
+++ b/core/lib/Drupal/Core/Cache/Context/PagersCacheContext.php
@@ -9,6 +9,10 @@
 
 /**
  * Defines a cache context for "per page in a pager" caching.
+ *
+ * Cache context ID: 'url.query_args.pagers' (to vary by all pagers).
+ * Calculated cache context ID: 'url.query_args.pagers:%pager_id', e.g.
+ * 'url.query_args.pagers:1' (to vary by the pager with ID 1).
  */
 class PagersCacheContext extends RequestStackCacheContextBase implements CalculatedCacheContextInterface {
 
diff --git a/core/lib/Drupal/Core/Cache/Context/QueryArgsCacheContext.php b/core/lib/Drupal/Core/Cache/Context/QueryArgsCacheContext.php
index e9a76649836c..faceb076c999 100644
--- a/core/lib/Drupal/Core/Cache/Context/QueryArgsCacheContext.php
+++ b/core/lib/Drupal/Core/Cache/Context/QueryArgsCacheContext.php
@@ -10,9 +10,9 @@
 /**
  * Defines the QueryArgsCacheContext service, for "per query args" caching.
  *
- * A "host" is defined as the combination of URI scheme, domain name and port.
- *
- * @see Symfony\Component\HttpFoundation::getSchemeAndHttpHost()
+ * Cache context ID: 'url.query_args' (to vary by all query arguments).
+ * Calculated cache context ID: 'url.query_args:%key', e.g.'url.query_args:foo'
+ * (to vary by the 'foo' query argument).
  */
 class QueryArgsCacheContext extends RequestStackCacheContextBase implements CalculatedCacheContextInterface {
 
diff --git a/core/lib/Drupal/Core/Cache/Context/RequestFormatCacheContext.php b/core/lib/Drupal/Core/Cache/Context/RequestFormatCacheContext.php
index c3e544d83490..b6784f7b89a5 100644
--- a/core/lib/Drupal/Core/Cache/Context/RequestFormatCacheContext.php
+++ b/core/lib/Drupal/Core/Cache/Context/RequestFormatCacheContext.php
@@ -9,6 +9,8 @@
 
 /**
  * Defines the RequestFormatCacheContext service, for "per format" caching.
+ *
+ * Cache context ID: 'request_format'.
  */
 class RequestFormatCacheContext extends RequestStackCacheContextBase {
 
diff --git a/core/lib/Drupal/Core/Cache/Context/RouteCacheContext.php b/core/lib/Drupal/Core/Cache/Context/RouteCacheContext.php
index 0643d8bf0ffd..bb4dd8d625fb 100644
--- a/core/lib/Drupal/Core/Cache/Context/RouteCacheContext.php
+++ b/core/lib/Drupal/Core/Cache/Context/RouteCacheContext.php
@@ -11,6 +11,8 @@
 
 /**
  * Defines the RouteCacheContext service, for "per route" caching.
+ *
+ * Cache context ID: 'route'.
  */
 class RouteCacheContext implements CacheContextInterface {
 
diff --git a/core/lib/Drupal/Core/Cache/Context/RouteNameCacheContext.php b/core/lib/Drupal/Core/Cache/Context/RouteNameCacheContext.php
index dcca18b8ff18..487edc288b0d 100644
--- a/core/lib/Drupal/Core/Cache/Context/RouteNameCacheContext.php
+++ b/core/lib/Drupal/Core/Cache/Context/RouteNameCacheContext.php
@@ -9,6 +9,8 @@
 
 /**
  * Defines the RouteCacheContext service, for "per route name" caching.
+ *
+ * Cache context ID: 'route.name'.
  */
 class RouteNameCacheContext extends RouteCacheContext {
 
diff --git a/core/lib/Drupal/Core/Cache/Context/SiteCacheContext.php b/core/lib/Drupal/Core/Cache/Context/SiteCacheContext.php
index 4e0c123f5119..e4d28cb4c3c4 100644
--- a/core/lib/Drupal/Core/Cache/Context/SiteCacheContext.php
+++ b/core/lib/Drupal/Core/Cache/Context/SiteCacheContext.php
@@ -10,6 +10,8 @@
 /**
  * Defines the SiteCacheContext service, for "per site" caching.
  *
+ * Cache context ID: 'site'.
+ *
  * A "site" is defined as the combination of URI scheme, domain name, port and
  * base path. It allows for varying between the *same* site being accessed via
  * different entry points. (Different sites in a multisite setup have separate
diff --git a/core/lib/Drupal/Core/Cache/Context/ThemeCacheContext.php b/core/lib/Drupal/Core/Cache/Context/ThemeCacheContext.php
index 85ba1a78975b..0a66878b0f8c 100644
--- a/core/lib/Drupal/Core/Cache/Context/ThemeCacheContext.php
+++ b/core/lib/Drupal/Core/Cache/Context/ThemeCacheContext.php
@@ -12,6 +12,8 @@
 
 /**
  * Defines the ThemeCacheContext service, for "per theme" caching.
+ *
+ * Cache context ID: 'theme'.
  */
 class ThemeCacheContext implements CacheContextInterface {
 
diff --git a/core/lib/Drupal/Core/Cache/Context/TimeZoneCacheContext.php b/core/lib/Drupal/Core/Cache/Context/TimeZoneCacheContext.php
index 7e5b7c5c94d9..9b22e0e286f9 100644
--- a/core/lib/Drupal/Core/Cache/Context/TimeZoneCacheContext.php
+++ b/core/lib/Drupal/Core/Cache/Context/TimeZoneCacheContext.php
@@ -10,6 +10,8 @@
 /**
  * Defines the TimeZoneCacheContext service, for "per time zone" caching.
  *
+ * Cache context ID: 'timezone'.
+ *
  * @see \Drupal\Core\Session\AccountProxy::setAccount()
  */
 class TimeZoneCacheContext implements CacheContextInterface {
diff --git a/core/lib/Drupal/Core/Cache/Context/UrlCacheContext.php b/core/lib/Drupal/Core/Cache/Context/UrlCacheContext.php
index 1ea0bf03ebdf..c0b0453d6a16 100644
--- a/core/lib/Drupal/Core/Cache/Context/UrlCacheContext.php
+++ b/core/lib/Drupal/Core/Cache/Context/UrlCacheContext.php
@@ -9,6 +9,8 @@
 
 /**
  * Defines the UrlCacheContext service, for "per page" caching.
+ *
+ * Cache context ID: 'url'.
  */
 class UrlCacheContext extends RequestStackCacheContextBase {
 
diff --git a/core/lib/Drupal/Core/Cache/Context/UserCacheContext.php b/core/lib/Drupal/Core/Cache/Context/UserCacheContext.php
index 80ad5191e60f..d7b80517bf86 100644
--- a/core/lib/Drupal/Core/Cache/Context/UserCacheContext.php
+++ b/core/lib/Drupal/Core/Cache/Context/UserCacheContext.php
@@ -11,6 +11,8 @@
 
 /**
  * Defines the UserCacheContext service, for "per user" caching.
+ *
+ * Cache context ID: 'user'.
  */
 class UserCacheContext implements CacheContextInterface {
 
diff --git a/core/lib/Drupal/Core/Cache/Context/UserRolesCacheContext.php b/core/lib/Drupal/Core/Cache/Context/UserRolesCacheContext.php
index 55cca784fd02..e4bb71a3f525 100644
--- a/core/lib/Drupal/Core/Cache/Context/UserRolesCacheContext.php
+++ b/core/lib/Drupal/Core/Cache/Context/UserRolesCacheContext.php
@@ -12,6 +12,10 @@
  *
  * Only use this cache context when checking explicitly for certain roles. Use
  * user.permissions for anything that checks permissions.
+ *
+ * Cache context ID: 'user.roles' (to vary by all roles of the current user).
+ * Calculated cache context ID: 'user.roles:%role', e.g. 'user.roles:anonymous'
+ * (to vary by the presence/absence of a specific role).
  */
 class UserRolesCacheContext extends UserCacheContext implements CalculatedCacheContextInterface{
 
diff --git a/core/modules/book/src/Cache/BookNavigationCacheContext.php b/core/modules/book/src/Cache/BookNavigationCacheContext.php
index 15ce15ad85a1..04a09e8dd4fb 100644
--- a/core/modules/book/src/Cache/BookNavigationCacheContext.php
+++ b/core/modules/book/src/Cache/BookNavigationCacheContext.php
@@ -14,6 +14,8 @@
 /**
  * Defines the book navigation cache context service.
  *
+ * Cache context ID: 'route.book_navigation'.
+ *
  * This allows for book navigation location-aware caching. It depends on:
  * - whether the current route represents a book node at all
  * - and if so, where in the book hierarchy we are
diff --git a/core/modules/node/src/Cache/NodeAccessGrantsCacheContext.php b/core/modules/node/src/Cache/NodeAccessGrantsCacheContext.php
index a0249f081c15..912309f42236 100644
--- a/core/modules/node/src/Cache/NodeAccessGrantsCacheContext.php
+++ b/core/modules/node/src/Cache/NodeAccessGrantsCacheContext.php
@@ -13,6 +13,10 @@
 /**
  * Defines the node access view cache context service.
  *
+ * Cache context ID: 'user.node_grants' (to vary by all operations' grants).
+ * Calculated cache context ID: 'user.node_grants:%operation', e.g.
+ * 'user.node_grants:view' (to vary by the view operation's grants).
+ *
  * This allows for node access grants-sensitive caching when listing nodes.
  *
  * @see node_query_node_access_alter()
diff --git a/core/modules/system/tests/modules/entity_test/src/Cache/EntityTestViewGrantsCacheContext.php b/core/modules/system/tests/modules/entity_test/src/Cache/EntityTestViewGrantsCacheContext.php
index 1bc28f11c89a..0b4b360d5fc1 100644
--- a/core/modules/system/tests/modules/entity_test/src/Cache/EntityTestViewGrantsCacheContext.php
+++ b/core/modules/system/tests/modules/entity_test/src/Cache/EntityTestViewGrantsCacheContext.php
@@ -12,6 +12,8 @@
 /**
  * Defines the entity_test view grants cache context service.
  *
+ * Cache context ID: 'entity_test_view_grants'.
+ *
  * @see \Drupal\node\Cache\NodeAccessViewGrantsCacheContext
  */
 class EntityTestViewGrantsCacheContext implements CacheContextInterface {
diff --git a/core/modules/views/tests/modules/views_test_data/src/Cache/ViewsTestCacheContext.php b/core/modules/views/tests/modules/views_test_data/src/Cache/ViewsTestCacheContext.php
index b66ba3830a53..25be6468fe75 100644
--- a/core/modules/views/tests/modules/views_test_data/src/Cache/ViewsTestCacheContext.php
+++ b/core/modules/views/tests/modules/views_test_data/src/Cache/ViewsTestCacheContext.php
@@ -11,6 +11,8 @@
 
 /**
  * Test cache context which uses a dynamic context coming from state.
+ *
+ * Cache context ID: 'views_test_cache_context'.
  */
 class ViewsTestCacheContext implements CacheContextInterface {
 
-- 
GitLab