Improve doc

symfony · geoffrey-brier · Dec 11, 2016 · Dec 23, 2016 · Dec 28, 2016 · Jan 26, 2017
commit 9cb31b2f3838341c6a892a48adc5ef2623eb6707
diff --git a/components/cache/cache_pools.rst b/components/cache/cache_pools.rst
@@ -4,6 +4,8 @@
    single: Doctrine Cache
    single: Redis Cache
 
+.. _component-cache-cache-pools:
+
 Cache Pools
 ===========
 

diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst
@@ -1476,6 +1476,12 @@ app
 
 The cache adapter used by the ``cache.app`` service.
 
+.. tip::
+
+    It might be tough to understand at the beginning, so to avoid confusion remember that all pools perform the
+    same actions but on different medium given the adapter they are based on. Internally, a pool wraps the definition
+    of an adapter.
+
 .. note::
 
     The framework bundle ships with multiple adapters: apcu, doctrine, system,
@@ -1524,6 +1530,10 @@ pools
 
 A list of cache pools to be created by the framework extension.
 
+.. seealso::
+
+    For more information about how pools works, see :ref:`cache pools <component-cache-cache-pools>`.
+
 .. _reference-cache-pools-name:
 
 name
@@ -1542,7 +1552,11 @@ adapter
 
 **type**: ``string`` **default**: ``cache.app``
 
-A cache adapter.
+The name of the adapter to use. You could also use your own implementation.
+
+.. note::
+
+    Your service MUST implement the :class:`Psr\\Cache\\CacheItemPoolInterface` interface.
 
 public
 ######
@@ -1574,7 +1588,7 @@ The cache clearer used to clear your PSR-6 cache.
 
 .. seealso::
 
-    For more information, see :class:`Symfony\\Component\\HttpKernel\\CacheClearer\\Psr6CacheClearer`
+    For more information, see :class:`Symfony\\Component\\HttpKernel\\CacheClearer\\Psr6CacheClearer`.
 
 Full Default Configuration
 --------------------------