Document the command-level @retries option

docs/guide/commands.rst

@@ -50,10 +50,47 @@ The following examples are functionally equivalent:
 Command parameters
 ------------------
 
-When you create a command using a client's ``getCommand()`` method, it does not
-immediately execute or transfer an HTTP request. The command is only executed
-when it is passed to the ``execute()`` method of the client. This gives you the
-opportunity to modify the command object before executing the command.
+All commands support a few special parameters that are not part of a service's
+API but instead control the SDK's behavior.
+
+``@http``
+~~~~~~~~~
+
+Using this parameter, it's possible to fine tune how the underlying HTTP handler
+executes the request. The options you can include in the ``@http`` parameter are
+the same as the ones you can set when you instantiate the client with the
+:ref:`"http" client option <config_http>`.
+
+.. code-block:: php
+
+    // Configures the command to be delayed by 500 milliseconds.
+    $command['@http'] = [
+        'delay' => 500,
+    ];
+
+``@retries``
+~~~~~~~~~~~~
+
+Like the :ref:`"retries" client option <config_retries>`, ``@retries`` controls
+how many times a command may be retried before it is considered to have failed.
+Set to ``0`` to disable retries.
+
+.. code-block:: php
+
+    // Disable retries
+    $command['@retries'] = 0;
+
+NB: If you have disabled retries on a client, you cannot selectively enable them
+on individual commands passed to that client.
+
+
+Creating command objects
+------------------------
+
+You can create a command using a client's ``getCommand()`` method. It does not
+immediately execute or transfer an HTTP request, but is only executed when it is
+passed to the ``execute()`` method of the client. This gives you the opportunity
+to modify the command object before executing the command.
 
 .. code-block:: php
 
@@ -71,23 +108,6 @@ opportunity to modify the command object before executing the command.
     $result = $s3Client->execute($command);
 
 
-HTTP handler options
---------------------
-
-All commands support the special ``@http`` parameter. Using this parameter,
-it's possible to fine tune how the underlying HTTP handler executes the
-request. The options you can include in the ``@http`` parameter are the same as
-the ones you can set when you instantiate the client with the
-:ref:`"http" client option <config_http>`.
-
-.. code-block:: php
-
-    // Configures the command to be delayed by 500 milliseconds.
-    $command['@http'] = [
-        'delay' => 500,
-    ];
-
-
 Command HandlerList
 -------------------
 

docs/guide/configuration.rst

@@ -621,6 +621,7 @@ for a list of available regions.
         'version' => '2006-03-01'
     ]);
 
+.. _config_retries:
 
 retries
 ~~~~~~~

src/RetryMiddleware.php

@@ -55,8 +55,8 @@ public static function createDefaultDecider($maxRetries = 3)
             $error = null
         ) use ($maxRetries) {
             // Allow command-level options to override this value
-            $maxRetries = null !== $command['retries'] ?
-                $command['retries']
+            $maxRetries = null !== $command['@retries'] ?
+                $command['@retries']
                 : $maxRetries;
 
             if ($retries >= $maxRetries) {

tests/RetryMiddlewareTest.php

@@ -210,7 +210,7 @@ function () use (&$called) { $called[] = func_get_args(); }
     public function testRetriesCanBeDisabledOnACommand()
     {
         $decider = RetryMiddleware::createDefaultDecider($retries = 3);
-        $command = new Command('foo', ['retries' => 0]);
+        $command = new Command('foo', ['@retries' => 0]);
         $request = new Request('GET', 'http://www.example.com');
         $err = new AwsException('e', $command, ['connection_error' => true]);
         $this->assertFalse($decider(0, $command, $request, null, $err));

tests/S3/S3ClientTest.php

@@ -363,6 +363,7 @@ public function testRetriesConnectionErrors()
         $client = new S3Client([
             'version' => 'latest',
             'region' => 'us-west-2',
+            'retries' => $retries,
             'http_handler' => function (
                 RequestInterface $request,
                 array $options
@@ -383,7 +384,6 @@ public function testRetriesConnectionErrors()
 
         $client->headBucket([
             'Bucket' => 'bucket',
-            'retries' => $retries,
         ]);
     }
 }

tests/WaiterTest.php

@@ -65,6 +65,7 @@ public function testContinueWaitingOnHandlerError()
         $client = new DynamoDbClient([
             'version' => 'latest',
             'region' => 'us-west-2',
+            'retries' => 0,
             'http_handler' => function (
                 RequestInterface $request,
                 array $options
@@ -87,7 +88,6 @@ public function testContinueWaitingOnHandlerError()
 
         $client->waitUntil('TableExists', [
             'TableName' => 'table',
-            'retries' => 0,
         ]);
     }