update documentation

src/Auth/AuthSchemeResolver.php

@@ -6,13 +6,22 @@
 use Aws\Identity\BearerTokenIdentity;
 use Aws\Identity\IdentityInterface;
 
+/**
+ * Houses logic for selecting an auth scheme modeled in a service's `auth` trait.
+ * The `auth` trait can be modeled either in a service's metadata, or at the operation level.
+ */
 class AuthSchemeResolver implements AuthSchemeResolverInterface
 {
     /**
-     * @var array
+     * @var array Mapping of auth schemes to signature versions used in
+     *            resolving a signature version.
      */
     private $authSchemeMap;
 
+    /**
+     * @var string[] Default mapping of modeled auth trait auth schemes
+     *               to the SDK's supported signature versions.
+     */
     private static $defaultAuthSchemeMap = [
         'aws.auth#sigv4' => 'v4',
         'aws.auth#sigv4a' => 'v4a',
@@ -28,6 +37,11 @@ public function __construct(array $authSchemeMap = [])
     }
 
     /**
+     * Accepts a priority-ordered list of auth schemes and an Identity
+     * and selects the first compatible auth schemes, returning a normalized
+     * signature version.  For example, based on the default auth scheme mapping,
+     * if `aws.auth#sigv4` is selected, `v4` will be returned.
+     *
      * @param array $authSchemes
      * @param $identity
      *
@@ -60,6 +74,9 @@ public function selectAuthScheme(
     }
 
     /**
+     * Determines compatibility based on either Identity or the availability
+     * of the CRT extension.
+     *
      * @param $authScheme
      * @param $identity
      *
@@ -85,6 +102,9 @@ private function isCompatibleAuthScheme($authScheme, $identity): bool
     }
 
     /**
+     * Provides incompatibility messages in the event an incompatible auth scheme
+     * is encountered.
+     *
      * @param $authScheme
      *
      * @return string

src/Auth/AuthSchemeResolverInterface.php

@@ -5,13 +5,16 @@
 use Aws\Identity\IdentityInterface;
 
 /**
- *
+ * An AuthSchemeResolver object determines which auth scheme will be used for request signing.
  */
 interface AuthSchemeResolverInterface
 {
     /**
-     * @param array $authSchemes
-     * @param IdentityInterface $identity
+     * Selects an auth scheme for request signing.
+     *
+     * @param array $authSchemes a priority-ordered list of authentication schemes.
+     * @param IdentityInterface $identity Credentials to be used in request signing.
+     *
      * @return string
      */
     public function selectAuthScheme(

src/Auth/AuthSelectionMiddleware.php

@@ -7,10 +7,12 @@
 use GuzzleHttp\Promise\Promise;
 
 /**
- * Handles auth scheme resolution.
+ * Handles auth scheme resolution. If a service models and auth scheme using
+ * the `auth` trait and the operation or metadata levels, this middleware will
+ * attempt to select the first compatible auth scheme it encounters and apply its
+ * signature version to the command's `@context` property bag.
  *
  * IMPORTANT: this middleware must be added to the "build" step.
- * Specifically, it must precede the 'endpoint-v2-middleware' step.
  *
  * @internal
  */
@@ -19,7 +21,7 @@ class AuthSelectionMiddleware
     /** @var callable */
     private $nextHandler;
 
-    /** @var callable | AuthResolver */
+    /** @var AuthSchemeResolverInterface */
     private $authResolver;
 
     /** @var callable */
@@ -82,14 +84,15 @@ public function __construct(
     public function __invoke(CommandInterface $command)
     {
         $nextHandler = $this->nextHandler;
-        $identityFn = $this->identityProvider;
-        $identity = $identityFn()->wait();
         $serviceAuth = $this->api->getMetadata('auth') ?: [];
         $operation = $this->api->getOperation($command->getName());
         $operationAuth = isset($operation['auth']) ? $operation['auth'] : [];
         $resolvableAuth = $operationAuth ?: $serviceAuth;
 
         if (!empty($resolvableAuth)) {
+            $identityFn = $this->identityProvider;
+            $identity = $identityFn()->wait();
+
             if (isset($command['@context']['authResolver'])
                 && $command['@context']['authResolver'] instanceof AuthSchemeResolverInterface
             ){

src/Auth/Exception/AuthException.php

@@ -2,5 +2,9 @@
 
 namespace Aws\Auth\Exception;
 
+use Aws\Exception\AwsException;
 
-class AuthException extends \RuntimeException {}
+/**
+ * Represents an error when attempting to resolve authentication.
+ */
+class AuthException extends AwsException {}

src/ClientResolver.php

@@ -122,7 +122,7 @@ class ClientResolver
         'auth_scheme_resolver' => [
             'type'    => 'value',
             'valid'   => [AuthSchemeResolverInterface::class],
-            'doc'     => 'A callable or Aws\Auth\AuthResolver object which accept a priority-ordered list of auth scheme versions and an identity and returns an auth scheme version',
+            'doc'     => 'An instance of Aws\Auth\AuthSchemeResolverInterface which selects a modeled auth scheme and returns a signature version',
             'default' => [__CLASS__, '_default_auth_scheme_resolver'],
         ],
         'api_provider' => [

src/Command.php

@@ -66,9 +66,9 @@ public function getHandlerList()
      *
      * @returns array
      *
-     * @deprecated In favor of using the @context key.
-     * Auth schemes are now accessible via the `signature_version` key
-     * in a Command's context, if applicable.
+     * @deprecated In favor of using the @context property bag.
+     *             Auth schemes are now accessible via the `signature_version` key
+     *             in a Command's context, if applicable.
      */
     public function getAuthSchemes()
     {

src/Identity/IdentityInterface.php

@@ -2,6 +2,9 @@
 
 namespace Aws\Identity;
 
+/**
+ * @internal
+ */
 interface IdentityInterface
 {
     /**