Fix documentation of credentials classes and modules in aws-sdk-core (#3306)

Author: ybiquitous

gems/aws-sdk-core/lib/aws-sdk-core/assume_role_credentials.rb

@@ -7,7 +7,7 @@ module Aws
   # {Aws::STS::Client#assume_role}.
   #
   #     role_credentials = Aws::AssumeRoleCredentials.new(
-  #       client: Aws::STS::Client.new(...),
+  #       client: Aws::STS::Client.new(sts_options),
   #       role_arn: "linked::account::arn",
   #       role_session_name: "session-name"
   #     )
@@ -28,15 +28,15 @@ class AssumeRoleCredentials
     # @option options [Integer] :duration_seconds
     # @option options [String] :external_id
     # @option options [STS::Client] :client
-    # @option options [Callable] before_refresh Proc called before
+    # @option options [Proc] :before_refresh A Proc called before
     #   credentials are refreshed.  Useful for updating tokens.
-    #   `before_refresh` is called when AWS credentials are
-    #   required and need to be refreshed. Tokens can be refreshed using
-    #   the following example:
+    #   `:before_refresh` is called when AWS credentials are
+    #   required and need to be refreshed. See the example in this doc.
     #
-    #      before_refresh = Proc.new do |assume_role_credentials| do
-    #        assume_role_credentials.assume_role_params['token_code'] = update_token
-    #      end
+    # @example Tokens can be refreshed using a Proc.
+    #   before_refresh = Proc.new do |assume_role_credentials|
+    #     assume_role_credentials.assume_role_params['token_code'] = update_token
+    #   end
     #
     def initialize(options = {})
       client_opts = {}

gems/aws-sdk-core/lib/aws-sdk-core/assume_role_web_identity_credentials.rb

@@ -9,11 +9,11 @@ module Aws
   # {Aws::STS::Client#assume_role_with_web_identity}.
   #
   #     role_credentials = Aws::AssumeRoleWebIdentityCredentials.new(
-  #       client: Aws::STS::Client.new(...),
+  #       client: Aws::STS::Client.new(sts_options),
   #       role_arn: "linked::account::arn",
   #       web_identity_token_file: "/path/to/token/file",
   #       role_session_name: "session-name"
-  #       ...
+  #       # ...
   #     )
   #     ec2 = Aws::EC2::Client.new(credentials: role_credentials)
   #

gems/aws-sdk-core/lib/aws-sdk-core/ecs_credentials.rb

@@ -42,26 +42,26 @@ class InvalidTokenError < RuntimeError; end
     # @option options [Integer] :retries (5) Number of times to retry
     #   when retrieving credentials.
     # @option options [String] :ip_address ('169.254.170.2') This value is
-    #   ignored if `endpoint` is set and `credential_path` is not set.
-    # @option options [Integer] :port (80) This value is ignored if `endpoint`
-    #   is set and `credential_path` is not set.
+    #   ignored if `:endpoint` is set and `:credential_path` is not set.
+    # @option options [Integer] :port (80) This value is ignored if `:endpoint`
+    #   is set and `:credential_path` is not set.
     # @option options [String] :credential_path By default, the value of the
-    #   AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable.
+    #   `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` environment variable.
     # @option options [String] :endpoint The container credential endpoint.
-    #   By default, this is the value of the AWS_CONTAINER_CREDENTIALS_FULL_URI
-    #   environment variable. This value is ignored if `credential_path` or
-    #   ENV['AWS_CONTAINER_CREDENTIALS_RELATIVE_URI'] is set.
+    #   By default, this is the value of the `AWS_CONTAINER_CREDENTIALS_FULL_URI`
+    #   environment variable. This value is ignored if `:credential_path` or
+    #   `ENV['AWS_CONTAINER_CREDENTIALS_RELATIVE_URI']` is set.
     # @option options [Float] :http_open_timeout (5)
     # @option options [Float] :http_read_timeout (5)
-    # @option options [Numeric, Proc] :delay By default, failures are retried
+    # @option options [IO] :http_debug_output (nil) HTTP wire
+    #   traces are sent to this object.  You can specify something
+    #   like `$stdout`.
+    # @option options [Numeric, Proc] :backoff By default, failures are retried
     #   with exponential back-off, i.e. `sleep(1.2 ** num_failures)`. You can
     #   pass a number of seconds to sleep between failed attempts, or
     #   a Proc that accepts the number of failures.
-    # @option options [IO] :http_debug_output (nil) HTTP wire
-    #   traces are sent to this object.  You can specify something
-    #   like $stdout.
-    # @option options [Callable] before_refresh Proc called before
-    #   credentials are refreshed. `before_refresh` is called
+    # @option options [Proc] :before_refresh A Proc called before
+    #   credentials are refreshed. `:before_refresh` is called
     #   with an instance of this object when
     #   AWS credentials are required and need to be refreshed.
     def initialize(options = {})

gems/aws-sdk-core/lib/aws-sdk-core/refreshing_credentials.rb

@@ -3,20 +3,21 @@
 module Aws
   # Base class used credential classes that can be refreshed. This
   # provides basic refresh logic in a thread-safe manner. Classes mixing in
-  # this module are expected to implement a #refresh method that populates
+  # this module are expected to implement a `#refresh` method that populates
   # the following instance variables:
   #
-  # * `@access_key_id`
-  # * `@secret_access_key`
-  # * `@session_token`
-  # * `@expiration`
+  # * `@credentials` ({Credentials})
+  # * `@expiration` (Time)
   #
   module RefreshingCredentials
     SYNC_EXPIRATION_LENGTH = 300 # 5 minutes
     ASYNC_EXPIRATION_LENGTH = 600 # 10 minutes
 
     CLIENT_EXCLUDE_OPTIONS = Set.new([:before_refresh]).freeze
 
+    # @param [Hash] options
+    # @option options [Proc] :before_refresh A Proc called before credentials are refreshed.
+    #   It accepts `self` as the only argument.
     def initialize(options = {})
       @mutex = Mutex.new
       @before_refresh = options.delete(:before_refresh) if options.is_a?(Hash)

gems/aws-sdk-core/lib/aws-sdk-core/sso_credentials.rb

@@ -7,7 +7,7 @@ module Aws
   # {Aws::SSOTokenProvider} will be used to refresh the token if possible.
   # This class does NOT implement the SSO login token flow - tokens
   # must generated separately by running `aws login` from the
-  # AWS CLI with the correct profile. The `SSOCredentials` will
+  # AWS CLI with the correct profile. The {SSOCredentials} will
   # auto-refresh the AWS credentials from SSO.
   #
   #     # You must first run aws sso login --profile your-sso-profile