feature #7245 [Cache] Document "framework.cache" nodes (geoffrey-brier, javiereguiluz)

This PR was submitted for the 3.1 branch but it was merged into the 3.2 branch instead (closes #7245).

Discussion
----------

[Cache] Document "framework.cache" nodes

Commits
-------

c4f0e38 Improve doc
9b0e46e Minor fixes
12e9a3c [Cache] Document "framework.cache" node

Author: xabbuh

components/cache/cache_pools.rst

@@ -5,6 +5,8 @@
    single: Redis Cache
    single: PDO Cache, Doctrine DBAL Cache
 
+.. _component-cache-cache-pools:
+
 Cache Pools
 ===========
 

reference/configuration/framework.rst

@@ -106,6 +106,19 @@ Configuration
     * `log`_
     * `throw`_
 * :ref:`cache <reference-cache>`
+    * :ref:`app <reference-cache-app>`
+    * `system`_
+    * `directory`_
+    * `default_doctrine_provider`_
+    * `default_psr6_provider`_
+    * `default_redis_provider`_
+    * `pools`_
+        * :ref:`name <reference-cache-pools-name>`
+            * `adapter`_
+            * `public`_
+            * `default_lifetime`_
+            * `provider`_
+            * `clearer`_
     * `prefix_seed`_
 
 secret
@@ -696,6 +709,8 @@ installation.
     You can see an example of the usage of this in
     :doc:`/doctrine/pdo_session_storage`.
 
+.. _name:
+
 name
 ....
 
@@ -1567,6 +1582,129 @@ Throw PHP errors as ``\ErrorException`` instances. The parameter
 cache
 ~~~~~
 
+.. _reference-cache-app:
+
+app
+...
+
+**type**: ``string`` **default**: ``cache.adapter.filesystem``
+
+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,
+    filesystem, psr6, and redis.
+
+system
+......
+
+**type**: ``string`` **default**: ``cache.adapter.system``
+
+The cache adapter used by the ``cache.system`` service.
+
+directory
+.........
+
+**type**: ``string`` **default**: ``%kernel.cache_dir%/pools``
+
+The path to the cache directory used by services inheriting from the
+``cache.adapter.filesystem`` adapter (including ``cache.app``).
+
+default_doctrine_provider
+.........................
+
+**type**: ``string``
+
+The service name to use as your default Doctrine provider.
+
+default_psr6_provider
+.....................
+
+**type**: ``string`` **default**: ``%kernel.cache_dir%/pools``
+
+The service name to use as your default PSR-6 provider.
+
+default_redis_provider
+......................
+
+**type**: ``string`` **default**: ``redis://localhost``
+
+The dsn to use by the Redis provider.
+
+pools
+.....
+
+**type**: ``array``
+
+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
+""""
+
+**type**: ``prototype``
+
+Name of the pool you want to create.
+
+.. note::
+
+    Your pool name must differ from ``cache.app`` or ``cache.system``.
+
+adapter
+#######
+
+**type**: ``string`` **default**: ``cache.app``
+
+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
+######
+
+**type**: ``boolean`` **default**: ``false``
+
+Whether your service should be public or not.
+
+default_lifetime
+################
+
+**type**: ``integer``
+
+Default lifetime of your cache items in seconds.
+
+provider
+########
+
+**type**: ``string``
+
+The service name to use as provider when the specified adapter needs one.
+
+clearer
+#######
+
+**type**: ``string``
+
+The cache clearer used to clear your PSR-6 cache.
+
+.. seealso::
+
+    For more information, see :class:`Symfony\\Component\\HttpKernel\\CacheClearer\\Psr6CacheClearer`.
+
 prefix_seed
 ...........
 
@@ -1724,6 +1862,23 @@ Full Default Configuration
                 log:                  false
                 throw:                '%kernel.debug%'
 
+            # cache configuration
+            cache:
+                app: cache.app
+                system: cache.system
+                directory: '%kernel.cache_dir%/pools'
+                default_doctrine_provider: ~
+                default_psr6_provider: ~
+                default_redis_provider: 'redis://localhost'
+                pools:
+                    # Prototype
+                    name:
+                        adapter: cache.app
+                        public: false
+                        default_lifetime: ~
+                        provider: ~
+                        clearer: ~
+
 .. _`HTTP Host header attacks`: http://www.skeletonscribe.net/2013/05/practical-http-host-header-attacks.html
 .. _`Security Advisory Blog post`: https://symfony.com/blog/security-releases-symfony-2-0-24-2-1-12-2-2-5-and-2-3-3-released#cve-2013-4752-request-gethost-poisoning
 .. _`Doctrine Cache`: http://docs.doctrine-project.org/projects/doctrine-common/en/latest/reference/caching.html