diff --git a/core/lib/Drupal/Core/Routing/CachedUrlGenerator.php b/core/lib/Drupal/Core/Routing/CachedUrlGenerator.php
index 1e634da..d6c5745 100644
--- a/core/lib/Drupal/Core/Routing/CachedUrlGenerator.php
+++ b/core/lib/Drupal/Core/Routing/CachedUrlGenerator.php
@@ -17,6 +17,9 @@
 
 /**
  * Class used to wrap a UrlGenerator to provide caching of the generated values.
+ *
+ * Caching occurs per URI, so that each cache entry comprises the generated URLs
+ * from that URI.
  */
 class CachedUrlGenerator implements DestructableInterface, CachedUrlGeneratorInterface {
 
@@ -89,10 +92,11 @@ public function __construct(UrlGeneratorInterface $url_generator, CacheBackendIn
     $this->cache = $cache;
     $this->routeProvider = $route_provider;
 
-    // Select cache.
+    // Select cache based on the current request URI. We store one entry for
+    // each URI.
     $this->cacheKey = $request_stack->getCurrentRequest()->getUri();
 
-    // Retrieve stored URLs
+    // Retrieve stored URLs.
     $cached = $this->cache->get($this->cacheKey);
     if ($cached) {
       $this->cachedUrls = $cached->data;
diff --git a/core/tests/Drupal/Tests/Core/Routing/CachedUrlGeneratorIntegrationTest.php b/core/tests/Drupal/Tests/Core/Routing/CachedUrlGeneratorIntegrationTest.php
index b0ef018..0965091 100644
--- a/core/tests/Drupal/Tests/Core/Routing/CachedUrlGeneratorIntegrationTest.php
+++ b/core/tests/Drupal/Tests/Core/Routing/CachedUrlGeneratorIntegrationTest.php
@@ -22,14 +22,14 @@ class CachedUrlGeneratorIntegrationTest extends WebTestBase {
   public function testCacheIsPopulated() {
 
     // Cache key and url.
-    $name =  $this->getAbsoluteUrl('/');
+    $name = $this->getAbsoluteUrl('/');
 
     // Populate the cache.
     $this->drupalGet($name);
 
     $cache = $this->container->get('cache.url_generator');
     // BAD - Use knowledge of an internal implementation detail to extract the
-    //  cache data!
+    // cache data!
     $data = $cache->get($name)->data;
     $this->assertFalse(empty($data), 'The cache has been primed.');
   }
diff --git a/core/tests/Drupal/Tests/Core/Routing/CachedUrlGeneratorTest.php b/core/tests/Drupal/Tests/Core/Routing/CachedUrlGeneratorTest.php
index 2b96bf8..7fa538b 100644
--- a/core/tests/Drupal/Tests/Core/Routing/CachedUrlGeneratorTest.php
+++ b/core/tests/Drupal/Tests/Core/Routing/CachedUrlGeneratorTest.php
@@ -100,6 +100,7 @@ public function testGenerate() {
       ->with('test_route')
       ->will($this->returnValue('test-route-1'));
     $this->assertEquals('test-route-1', $this->cachedUrlGenerator->generateFromRoute('test_route'));
+    // Second call will fetch from cache.
     $this->assertEquals('test-route-1', $this->cachedUrlGenerator->generateFromRoute('test_route'));
   }
 
@@ -116,8 +117,12 @@ public function testGenerateWithDifferentParameters() {
         array('test_route', array('key' => 'value2'), array(), 'test-route-1/value2'),
       )));
     $this->assertEquals('test-route-1/value1', $this->cachedUrlGenerator->generate('test_route', array('key' => 'value1')));
+    // Second call will fetch from cache.
     $this->assertEquals('test-route-1/value1', $this->cachedUrlGenerator->generate('test_route', array('key' => 'value1')));
+    // Third call uses the same route with different parameters, so will call
+    // into the UrlGenerator mock.
     $this->assertEquals('test-route-1/value2', $this->cachedUrlGenerator->generate('test_route', array('key' => 'value2')));
+    // Fourth call will fetch from cache.
     $this->assertEquals('test-route-1/value2', $this->cachedUrlGenerator->generate('test_route', array('key' => 'value2')));
   }
 
@@ -132,6 +137,7 @@ public function testGenerateFromPath() {
       ->with('test-route-1')
       ->will($this->returnValue('test-route-1'));
     $this->assertEquals('test-route-1', $this->cachedUrlGenerator->generateFromPath('test-route-1'));
+    // Second call will fetch from cache.
     $this->assertEquals('test-route-1', $this->cachedUrlGenerator->generateFromPath('test-route-1'));
   }
 
@@ -148,8 +154,12 @@ public function testGenerateFromPathWithDifferentParameters() {
         array('test-route-1', array('absolute' => FALSE), 'test-route-1'),
       )));
     $this->assertEquals('http://localhost/test-route-1', $this->cachedUrlGenerator->generateFromPath('test-route-1', array('absolute' => TRUE)));
+    // Second call will fetch from cache.
     $this->assertEquals('http://localhost/test-route-1', $this->cachedUrlGenerator->generateFromPath('test-route-1', array('absolute' => TRUE)));
+    // Third call uses the same route, with different parameters, so will call
+    // into the UrlGenerator mock.
     $this->assertEquals('test-route-1', $this->cachedUrlGenerator->generateFromPath('test-route-1', array('absolute' => FALSE)));
+    // Fourth call will fetch from cache.
     $this->assertEquals('test-route-1', $this->cachedUrlGenerator->generateFromPath('test-route-1', array('absolute' => FALSE)));
   }
 
@@ -165,6 +175,7 @@ public function testGenerateFromRoute() {
       ->with('test_route')
       ->will($this->returnValue('test-route-1'));
     $this->assertEquals('test-route-1', $this->cachedUrlGenerator->generateFromRoute('test_route'));
+    // Second call will fetch from cache.
     $this->assertEquals('test-route-1', $this->cachedUrlGenerator->generateFromRoute('test_route'));
   }
 
@@ -183,12 +194,22 @@ public function testGenerateFromRouteWithDifferentParameters() {
         array('test_route', array('key' => 'value2'), array('absolute' => TRUE), 'http://localhost/test-route-1/value2'),
       )));
     $this->assertEquals('test-route-1/value1', $this->cachedUrlGenerator->generateFromRoute('test_route', array('key' => 'value1')));
+    // Second call will fetch from cache.
     $this->assertEquals('test-route-1/value1', $this->cachedUrlGenerator->generateFromRoute('test_route', array('key' => 'value1')));
+    // Third call uses the same route, with different parameters, so will call
+    // into the UrlGenerator mock.
     $this->assertEquals('http://localhost/test-route-1/value1', $this->cachedUrlGenerator->generateFromRoute('test_route', array('key' => 'value1'), array('absolute' => TRUE)));
+    // Fourth call will fetch form cache.
     $this->assertEquals('http://localhost/test-route-1/value1', $this->cachedUrlGenerator->generateFromRoute('test_route', array('key' => 'value1'), array('absolute' => TRUE)));
+    // Fifth call uses the same route, with different parameters, so will call
+    // into the UrlGenerator mock.
     $this->assertEquals('test-route-1/value2', $this->cachedUrlGenerator->generateFromRoute('test_route', array('key' => 'value2')));
+    // Sixth call will fetch from cache.
     $this->assertEquals('test-route-1/value2', $this->cachedUrlGenerator->generateFromRoute('test_route', array('key' => 'value2')));
+    // Seventh call uses the same route, with different parameters, so will call
+    // into the UrlGenerator mock.
     $this->assertEquals('http://localhost/test-route-1/value2', $this->cachedUrlGenerator->generateFromRoute('test_route', array('key' => 'value2'), array('absolute' => TRUE)));
+    // Eighth call will fetch from cache.
     $this->assertEquals('http://localhost/test-route-1/value2', $this->cachedUrlGenerator->generateFromRoute('test_route', array('key' => 'value2'), array('absolute' => TRUE)));
   }