Minor tweaks

Author: javiereguiluz

http_client.rst

@@ -1488,22 +1488,23 @@ in the foreach loop::
         }
     }
 
+.. _http-client_caching:
+
 Caching Requests and Responses
 ------------------------------
 
 This component provides a :class:`Symfony\\Component\\HttpClient\\CachingHttpClient`
-decorator that allows caching responses and serving them from the cache storage
-for next requests as described in `RFC 9111`_.
+decorator that enables caching of HTTP responses and serving them from cache
+storage on subsequent requests, as described in `RFC 9111`_.
 
-The implementation leverages a
-:class:`tag aware cache <Symfony\\Contracts\\Cache\\TagAwareCacheInterface>` under the hood
-so the :doc:`Cache component </components/cache>` needs to be
-installed in your application.
+Internally, it relies on a :class:`tag aware cache <Symfony\\Contracts\\Cache\\TagAwareCacheInterface>`,
+so the :doc:`Cache component </components/cache>` must be installed in your application.
 
 .. tip::
 
-    The implementation is asynchronous, so the response must be consumed
-    (e.g., via getContent() or streaming) for caching to occur.
+    The caching mechanism is asynchronous. The response must be fully consumed
+    (for example, by calling ``getContent()`` or using a stream) for it to be
+    stored in the cache.
 
 .. configuration-block::
 
@@ -1586,14 +1587,15 @@ installed in your application.
 
 .. tip::
 
-    It is also highly recommended to configure a :ref:`retry strategy <http-client-retry-failed-requests>`
-    to gracefully handle cache inconsistency.
+    It is strongly recommended to configure a
+    :ref:`retry strategy <http-client-retry-failed-requests>` to gracefully
+    handle temporary cache inconsistencies or validation failures.
 
 .. versionadded:: 7.4
 
-    Compliance with `RFC 9111`_ and leveraging the
-    :doc:`Cache component </components/cache>` was introduced in Symfony 7.4.
-    Prior to this, it used ``HttpCache`` from the HttpKernel component.
+    In Symfony 7.4, caching was refactored to comply with `RFC 9111`_ and to
+    leverage the :doc:`Cache component </components/cache>`. In previous versions,
+    it relied on ``HttpCache`` from the HttpKernel component.
 
 Limit the Number of Requests
 ----------------------------

reference/configuration/framework.rst

@@ -1666,8 +1666,8 @@ caching
 
 **type**: ``array``
 
-This option configures the behavior of the HTTP client caching, including which
-types of requests to cache and how many times. The behavior is
+This option configures the behavior of the :ref:`HTTP client caching <http-client_caching>`,
+including which types of requests to cache and how many times. The behavior is
 defined with the following options:
 
 * :ref:`cache_pool <reference-http-client-caching-cache-pool>`
@@ -1710,27 +1710,38 @@ must implement the :class:`Symfony\\Contracts\\Cache\\TagAwareCacheInterface`.
 By default, it uses an instance of :class:`Symfony\\Component\\Cache\\Adapter\\TagAwareAdapter`
 wrapping the ``cache.app`` pool.
 
+.. versionadded:: 7.4
+
+    The ``cache_pool`` option was introduced in Symfony 7.4.
+
 .. _reference-http-client-caching-shared:
 
 shared
-"""""""
+""""""
 
 **type**: ``boolean`` **default**: ``true``
 
-Whether the cache is shared or private. If ``true``, the cache
-is `shared <https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Caching#shared_cache>`_
-(default), if ``false``, the cache is
-`private <https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Caching#private_caches>`_.
+If ``true``, it uses a `shared cache`_ so cached responses can be reused across
+users. Set it to ``false`` to use a `private cache`_.
+
+.. versionadded:: 7.4
+
+    The ``shared`` option was introduced in Symfony 7.4.
 
 .. _reference-http-client-caching-max-ttl:
 
 max_ttl
-"""""""""
+"""""""
 
 **type**: ``integer`` **default**: ``null``
 
-The maximum time-to-live (in seconds) for cached responses. Server-provided TTLs
-are capped to this value if set.
+The maximum time-to-live (in seconds) for cached responses. By default, responses
+are cached for as long as the TTL specified by the server. When this option is
+set, server-provided TTLs are capped to this value.
+
+.. versionadded:: 7.4
+
+    The ``max_ttl`` option was introduced in Symfony 7.4.
 
 cafile
 ......
@@ -4149,3 +4160,5 @@ to know their differences.
 .. _`Link HTTP header`: https://tools.ietf.org/html/rfc5988
 .. _`SMTP session`: https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol#SMTP_transport_example
 .. _`PHP attributes`: https://www.php.net/manual/en/language.attributes.overview.php
+.. _`public cache`: https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Caching#shared_cache
+.. _`private cache`: https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Caching#private_caches