updated syntax

Author: Nyholm

cache.rst

@@ -5,9 +5,7 @@ Using cache is a great way of making you application run quicker. The Symfony ca
 component is shipped with many adapters to different storages. Every adapter is
 developed for high performance.
 
-Basic uses of the cache looks like this.
-
-.. code-block:: php
+Basic uses of the cache looks like this::
 
     use Symfony\Contracts\Cache\ItemInterface;
 
@@ -27,11 +25,11 @@ Basic uses of the cache looks like this.
 
 
 Symfony also supports PSR-6 and PSR-16 cache interfaces. You can read more about
-these at the :ref:`component documentation <component-cache>`.
+these at the :doc:`component documentation </components/cache>`.
 
 
-Configuring Cache with SymfonyFrameworkBundle
----------------------------------------------
+Configuring Cache with FrameworkBundle
+--------------------------------------
 
 When configuring the the cache component there are a few concepts you should know
 of:
@@ -46,63 +44,65 @@ of:
 
 There are two pools that are always enabled by default. They are ``cache.app`` and
 ``cache.system``. The system cache is use for things like annotations, serializer,
-and validation. The ```cache.app`` is used in your code. You can configure which
+and validation. The ``cache.app`` can be used in your code. You can configure which
 adapter (template) they use by using the ``app`` and ``system`` key like:
 
 .. code-block:: yaml
 
+    # config/packages/cache.yaml
     framework:
         cache:
             app: cache.adapter.filesystem
             system: cache.adapter.system
 
 The Cache component comes with a series of adapters already created:
 
-- :ref:`cache.adapter.apcu <component-cache-apcu-adapter>`
-- :ref:`ChainAdapter <component-cache-chain-adapter>`
-- :ref:`cache.adapter.doctrine <component-cache-doctrine-adapter>`
-- :ref:`cache.adapter.filesystem <component-cache-filesystem-adapter>`
-- :ref:`cache.adapter.memcached <component-cache-memcached-adapter>`
-- :ref:`cache.adapter.pdo <component-cache-pdo-doctrine-dbal-adapter>`
-- :ref:`PHPArrayAdapter <component-cache-php-array-adapter>`
-- :ref:`PHPFileAdapter <component-cache-php-files-adapter>`
-- :ref:`ProxyAdapter <component-cache-proxy-adapter>`
-- :ref:`cache.adapter.redis <component-cache-redis-adapter>`
-- cache.adapter.psr6
-- cache.adapter.system
-- NullAdapter
-- cache.adapter.array
-
-Some of these adapters could be configured via shortcuts:
+* :doc:`cache.adapter.apcu </components/cache/adapters/apcu-adapter>`
+* :doc:`cache.adapter.array </components/cache/adapters/array-cache-adapter>`
+* :doc:`cache.adapter.doctrine </components/cache/adapters/doctrine-adapter>`
+* :doc:`cache.adapter.filesystem </components/cache/adapters/filesystem-adapter>`
+* :doc:`cache.adapter.memcached </components/cache/adapters/memcached-adapter>`
+* :doc:`cache.adapter.pdo </components/cache/adapters/pdo-doctrine-dbal-adapter>`
+* :doc:`cache.adapter.redis </components/cache/adapters/redis-adapter>`
+* :doc:`PHPFileAdapter </components/cache/adapters/php-files-adapter>`
+* :doc:`PHPArrayAdapter </components/cache/adapters/php-array-adapter>`
+
+* :doc:`ChainAdapter </components/cache/adapters/chain-adapter>`
+* :doc:`ProxyAdapter </components/cache/adapters/proxy-adapter>`
+* cache.adapter.psr6
+
+* cache.adapter.system
+* NullAdapter
+
+Some of these adapters could be configured via shortcuts. Using these shortcuts
+will create pool with service id of ``cache.[type]``
 
 .. code-block:: yaml
 
+    # config/packages/cache.yaml
     framework:
         cache:
             directory: '%kernel.cache_dir%/pools' # Only used with cache.adapter.filesystem
 
+            # service: cache.doctrine
             default_doctrine_provider: 'app.doctrine_cache'
+            # service: cache.psr6
             default_psr6_provider: 'app.my_psr6_service'
+            # service: cache.redis
             default_redis_provider: 'redis://localhost'
+            # service: cache.memcached
             default_memcached_provider: 'memcached://localhost'
+            # service: cache.pdo
             default_pdo_provider: 'doctrine.dbal.default_connection'
 
-Using the *providers* above, they will configure the adapters and create pools (services)
-with service ids:
-
-- ``cache.doctrine``
-- ``cache.psr6``
-- ``cache.redis``
-- ``cache.memcached``
-- ``cache.pdo``
-
 Creating Custom Pools
 ---------------------
 
-You can also create more customized pools. All you need is an adapter
+You can also create more customized pools. All you need is an adapter:
 
 .. code-block:: yaml
 
+    # config/packages/cache.yaml
     framework:
         cache:
             default_memcached_provider: 'memcached://localhost'
@@ -117,14 +117,15 @@ You can also create more customized pools. All you need is an adapter
 
 The configuration above will create 3 services: ``my_cache_pool``, ``cache.acme``
 and ``cache.foobar``.  The ``my_cache_pool`` pool is using the ArrayAdapter
-and the other two are using the :ref:`MemcachedAdapter <component-cache-memcached-adapter>`.
+and the other two are using the :doc:`MemcachedAdapter </components/cache/adapters/memcached-adapter>`.
 The ``cache.acme`` pool is using the Memcached server on localhost and ``cache.foobar``
 is using the Memcached server at example.com.
 
 For advanced configurations it could sometimes be useful to use a pool as an adapter.
 
 .. code-block:: yaml
 
+    # config/packages/cache.yaml
     framework:
         cache:
             pools:
@@ -145,17 +146,19 @@ Different cache adapters has different strengths and weaknesses. Some might be r
 quick but small and some may be able to contain a lot of data but are quite slow.
 To get the best of both worlds you may use a chain of adapters. The idea is to
 first look at the quick adapter and then move on to slower adapters. In the worst
-case we have to recalculate the value.
+case the value needs to be recalculated.
 
 .. code-block:: yaml
 
+    # config/services.yaml
     services:
         app.my_cache_chain_adapter:
             class: Symfony\Component\Cache\Adapter\ChainAdapter
             arguments:
                 - ['cache.adapter.array', 'cache.my_redis', 'cache.adapter.file']
                 - 31536000 # One year
 
+    # config/packages/cache.yaml
     framework:
         cache:
             pools:
@@ -189,4 +192,4 @@ clearer.
 
 .. code-block:: terminal
 
-    $ bin/console cache:pool:clear cache.app_clearer
+    $ php bin/console cache:pool:clear cache.app_clearer