Rewording

Author: Tiriel

http_client.rst

@@ -734,58 +734,59 @@ each retry.
 Retry over different uris
 .........................
 
-When using a ``RetryableHttpClient``, the ``base_uri`` can be set as an array of
-uris. The array will be used in the given order, meaning that the first request
-will be made with the first uri in the array. Should it fail, the next one will
-be used for the first retry. If the number of configured retries is greater than
-the number of given uris, the last uri will be used for every exceding retry.
+The ``RetryableHttpClient`` can be configured to use multiple base URIs. This
+feature provides increased flexibility and reliability for making HTTP
+requests. Pass an array of base URIs as option ``base_uri`` when making a 
+request:
 
-You can pass the array of base uris directly to the ``request`` method or when
-creating a HttpClient with the ``withOptions`` method::
-
-    use Symfony\Component\HttpClient\RetryableHttpClient;
-
-    $client = new RetryableHttpClient(HttpClient::create());
+.. code-block:: php
 
-    $response = $client->request('GET', 'some-path', [
+    $response = $client->request('GET', 'foo-bar', [
         'base_uri' => [
-            // first request will use this base uri
+            // first request will use this base URI
             'http://example.com/a/',
-            // if first request fails, the second base uri will be used
+            // if first request fails, this second base URI will be used
             'http://example.com/b/',
         ],
     ]);
 
-    // You can also use the withOptions method to pass an array of base_uri
-    $client = $client->withOptions(['base_uri' => [
-        'http://example.com/a/',
-        'http://example.com/b/',
-    ]]);
-
-    $response = $client->request('GET', 'some-path');
-
-If you wish some or all of the base uris to be shuffled, you can pass a nested
-array inside the ``base_uri`` array. Every uri inside the nested array will be
-randomized, and the order of the base uris outside this nested array will be
-preserved::
+When the number of retries is higher than the number of base URIs, the 
+last base URI will be used for remaining retries.
 
-    use Symfony\Component\HttpClient\RetryableHttpClient;
+If you want to shuffle the order of base URIs for each retry attempt, nest the
+base URIs you want to shuffle in an additional array:
 
-    $client = new RetryableHttpClient(HttpClient::create());
+.. code-block:: php
 
-    $response = $client->request('GET', 'some-path', [
+    $response = $client->request('GET', 'foo-bar', [
         'base_uri' => [
             'http://example.com/a/',
             [
-                // base uri passed inside a nested array will be shuffled
+                // one random URI from this list will be used on retry #2
                 'http://example.com/b/',
                 'http://example.com/c/',
             ],
-            // the order of the non-nested base uris is preserved
+            // non-nested base URIs are used in order
             'http://example.com/d/',
         ],
     ]);
 
+This feature allows for a more randomized approach to handling retries, 
+reducing the likelihood of repeatedly hitting the same failed base URI.
+
+By using a nested array for the base URI, you can use this feature 
+to distribute the load among many nodes in a cluster of servers.
+
+You can also configure the array of base URIs using the ``withOptions()`` 
+method:
+
+.. code-block:: php
+
+    $client = $client->withOptions(['base_uri' => [
+        'http://example.com/a/',
+        'http://example.com/b/',
+    ]]);
+
 HTTP Proxies
 ~~~~~~~~~~~~