Add rdoc to RBS and generation task

.gitignore

@@ -12,3 +12,4 @@ coverage
 *.DS_Store
 .idea
 .ruby-version
+/tmp

gems/aws-sdk-core/sig/aws-sdk-core.rbs

@@ -1,39 +1,321 @@
 module Aws
+  # <!-- rdoc-file=gems/aws-sdk-core/lib/aws-sdk-core.rb -->
+  # @return [Hash] Returns a hash of default configuration options shared
+  #     by all constructed clients.
+  #
   attr_reader self.config: Hash[Symbol, untyped]
+
+  # <!--
+  #   rdoc-file=gems/aws-sdk-core/lib/aws-sdk-core.rb
+  #   - use_bundled_cert!()
+  # -->
+  # The SDK ships with a ca certificate bundle to use when verifying SSL peer
+  # certificates. By default, this cert bundle is **NOT** used. The SDK will rely
+  # on the default cert available to OpenSSL. This ensures the cert provided by
+  # your OS is used.
+  #
+  # For cases where the default cert is unavailable, e.g. Windows, you can call
+  # this method.
+  #
+  #     Aws.use_bundled_cert!
+  #
+  # @return [String] Returns the path to the bundled cert.
+  #
   def self.use_bundled_cert!: () -> String
 
+  # <!-- rdoc-file=gems/aws-sdk-core/lib/aws-sdk-core/client_stubs.rb -->
+  # This module provides the ability to specify the data and/or errors to return
+  # when a client is using stubbed responses. Pass `:stub_responses => true` to a
+  # client constructor to enable this behavior.
+  #
+  # Also allows you to see the requests made by the client by reading the
+  # api_requests instance variable
+  #
   module ClientStubs
+    # <!--
+    #   rdoc-file=gems/aws-sdk-core/lib/aws-sdk-core/client_stubs.rb
+    #   - stub_responses(operation_name, *stubs)
+    # -->
+    # Configures what data / errors should be returned from the named operation when
+    # response stubbing is enabled.
+    #
+    # ## Basic usage
+    #
+    # When you enable response stubbing, the client will generate fake responses and
+    # will not make any HTTP requests.
+    #
+    #     client = Aws::S3::Client.new(stub_responses: true)
+    #     client.list_buckets
+    #     #=> #<struct Aws::S3::Types::ListBucketsOutput buckets=[], owner=nil>
+    #
+    # You can provide stub data that will be returned by the client.
+    #
+    #     # stub data in the constructor
+    #     client = Aws::S3::Client.new(stub_responses: {
+    #       list_buckets: { buckets: [{name: 'my-bucket' }] },
+    #       get_object: { body: 'data' },
+    #     })
+    #
+    #     client.list_buckets.buckets.map(&:name) #=> ['my-bucket']
+    #     client.get_object(bucket:'name', key:'key').body.read #=> 'data'
+    #
+    # You can also specify the stub data using {#stub_responses}
+    #
+    #     client = Aws::S3::Client.new(stub_responses: true)
+    #     client.stub_responses(:list_buckets, {
+    #       buckets: [{ name: 'my-bucket' }]
+    #     })
+    #
+    #     client.list_buckets.buckets.map(&:name)
+    #     #=> ['my-bucket']
+    #
+    # With a Resource class {#stub_responses} on the corresponding client:
+    #
+    #     s3 = Aws::S3::Resource.new(stub_responses: true)
+    #     s3.client.stub_responses(:list_buckets, {
+    #       buckets: [{ name: 'my-bucket' }]
+    #     })
+    #
+    #     s3.buckets.map(&:name)
+    #     #=> ['my-bucket']
+    #
+    # Lastly, default stubs can be configured via `Aws.config`:
+    #
+    #     Aws.config[:s3] = {
+    #       stub_responses: {
+    #         list_buckets: { buckets: [{name: 'my-bucket' }] }
+    #       }
+    #     }
+    #
+    #     Aws::S3::Client.new.list_buckets.buckets.map(&:name)
+    #     #=> ['my-bucket']
+    #
+    #     Aws::S3::Resource.new.buckets.map(&:name)
+    #     #=> ['my-bucket']
+    #
+    # ## Dynamic Stubbing
+    #
+    # In addition to creating static stubs, it's also possible to generate stubs
+    # dynamically based on the parameters with which operations were called, by
+    # passing a `Proc` object:
+    #
+    #     s3 = Aws::S3::Resource.new(stub_responses: true)
+    #     s3.client.stub_responses(:put_object, -> (context) {
+    #       s3.client.stub_responses(:get_object, content_type: context.params[:content_type])
+    #     })
+    #
+    # The yielded object is an instance of {Seahorse::Client::RequestContext}.
+    #
+    # ## Stubbing Errors
+    #
+    # When stubbing is enabled, the SDK will default to generate fake responses with
+    # placeholder values. You can override the data returned. You can also specify
+    # errors it should raise.
+    #
+    #     # simulate service errors, give the error code
+    #     client.stub_responses(:get_object, 'NotFound')
+    #     client.get_object(bucket:'aws-sdk', key:'foo')
+    #     #=> raises Aws::S3::Errors::NotFound
+    #
+    #     # to simulate other errors, give the error class, you must
+    #     # be able to construct an instance with `.new`
+    #     client.stub_responses(:get_object, Timeout::Error)
+    #     client.get_object(bucket:'aws-sdk', key:'foo')
+    #     #=> raises new Timeout::Error
+    #
+    #     # or you can give an instance of an error class
+    #     client.stub_responses(:get_object, RuntimeError.new('custom message'))
+    #     client.get_object(bucket:'aws-sdk', key:'foo')
+    #     #=> raises the given runtime error object
+    #
+    # ## Stubbing HTTP Responses
+    #
+    # As an alternative to providing the response data, you can provide an HTTP
+    # response.
+    #
+    #     client.stub_responses(:get_object, {
+    #       status_code: 200,
+    #       headers: { 'header-name' => 'header-value' },
+    #       body: "...",
+    #     })
+    #
+    # To stub a HTTP response, pass a Hash with all three of the following keys set:
+    #
+    # *   **`:status_code`** - <Integer> - The HTTP status code
+    # *   **`:headers`** - Hash<String,String> - A hash of HTTP header keys and
+    #     values
+    # *   **`:body`** - <String,IO> - The HTTP response body.
+    #
+    #
+    # ## Stubbing Multiple Responses
+    #
+    # Calling an operation multiple times will return similar responses. You can
+    # configure multiple stubs and they will be returned in sequence.
+    #
+    #     client.stub_responses(:head_object, [
+    #       'NotFound',
+    #       { content_length: 150 },
+    #     ])
+    #
+    #     client.head_object(bucket:'aws-sdk', key:'foo')
+    #     #=> raises Aws::S3::Errors::NotFound
+    #
+    #     resp = client.head_object(bucket:'aws-sdk', key:'foo')
+    #     resp.content_length #=> 150
+    #
+    # @param [Symbol] operation_name
+    #
+    # @param [Mixed] stubs One or more responses to return from the named
+    #     operation.
+    #
+    # @return [void]
+    #
+    # @raise [RuntimeError] Raises a runtime error when called
+    #     on a client that has not enabled response stubbing via
+    #     `:stub_responses => true`.
+    #
     def stub_responses: (Symbol operation_name, *untyped stubs) -> void
+
+    # <!--
+    #   rdoc-file=gems/aws-sdk-core/lib/aws-sdk-core/client_stubs.rb
+    #   - api_requests(options = {})
+    # -->
+    # Allows you to access all of the requests that the stubbed client has made.
+    #
+    # @param [Hash] options The options for the api requests. @option options
+    # [Boolean] :exclude_presign (false) Set to true to filter
+    #     out unsent requests from generated presigned urls.
+    #
+    # @return [Array] Returns an array of the api requests made. Each request
+    #     object contains the :operation_name, :params, and :context.
+    #
+    # @raise [NotImplementedError] Raises `NotImplementedError` when the client
+    #     is not stubbed.
+    #
     def api_requests: () -> Array[{ operation_name: Symbol, params: untyped, context: untyped }]
+
+    # <!--
+    #   rdoc-file=gems/aws-sdk-core/lib/aws-sdk-core/client_stubs.rb
+    #   - stub_data(operation_name, data = {})
+    # -->
+    # Generates and returns stubbed response data from the named operation.
+    #
+    #     s3 = Aws::S3::Client.new
+    #     s3.stub_data(:list_buckets)
+    #     #=> #<struct Aws::S3::Types::ListBucketsOutput buckets=[], owner=#<struct Aws::S3::Types::Owner display_name="DisplayName", id="ID">>
+    #
+    # In addition to generating default stubs, you can provide data to apply to the
+    # response stub.
+    #
+    #     s3.stub_data(:list_buckets, buckets:[{name:'aws-sdk'}])
+    #     #=> #<struct Aws::S3::Types::ListBucketsOutput
+    #       buckets=[#<struct Aws::S3::Types::Bucket name="aws-sdk", creation_date=nil>],
+    #       owner=#<struct Aws::S3::Types::Owner display_name="DisplayName", id="ID">>
+    #
+    # @param [Symbol] operation_name @param [Hash] data @return [Structure] Returns
+    # a stubbed response data structure. The
+    #     actual class returned will depend on the given `operation_name`.
+    #
     def stub_data: (Symbol operation_name, untyped data) -> untyped
   end
 
   module Errors
-    # The base class for all errors returned by an Amazon Web Service.
-    # All ~400 level client errors and ~500 level server errors are raised
-    # as service errors.  This indicates it was an error returned from the
-    # service and not one generated by the client.
+    # <!-- rdoc-file=gems/aws-sdk-core/lib/aws-sdk-core/errors.rb -->
+    # The base class for all errors returned by an Amazon Web Service. All ~400
+    # level client errors and ~500 level server errors are raised as service errors.
+    #  This indicates it was an error returned from the service and not one
+    # generated by the client.
+    #
     class ServiceError < RuntimeError
+      # <!-- rdoc-file=gems/aws-sdk-core/lib/aws-sdk-core/errors.rb -->
+      # @return [String]
+      #
       attr_reader code: String
+
+      # <!-- rdoc-file=gems/aws-sdk-core/lib/aws-sdk-core/errors.rb -->
+      # @return [Seahorse::Client::RequestContext] The context of the request
+      #     that triggered the remote service to return this error.
+      #
       attr_reader context: untyped
+
+      # <!-- rdoc-file=gems/aws-sdk-core/lib/aws-sdk-core/errors.rb -->
+      # @return [Aws::Structure]
+      #
       attr_reader data: untyped
+
+      # <!-- rdoc-file=gems/aws-sdk-core/lib/aws-sdk-core/errors.rb -->
+      # @return [String]
+      #
       attr_accessor self.code: String
     end
   end
 
+  # <!-- rdoc-file=gems/aws-sdk-core/lib/aws-sdk-core/structure.rb -->
+  # @api private
+  #
   class EmptyStructure
   end
 
   module Resources
     class Collection[T]
       include Enumerable[T]
+
+      # <!--
+      #   rdoc-file=gems/aws-sdk-core/lib/aws-sdk-core/resources/collection.rb
+      #   - new(batches, options = {})
+      # -->
+      # @param [Enumerator<Array>] batches @option options [Integer] :limit @option
+      # options [Integer] :size @api private
+      #
       def initialize: (Enumerable[Enumerable[T]] batches, ?size: Integer, ?limit: Integer) -> void
+
+      # <!--
+      #   rdoc-file=gems/aws-sdk-core/lib/aws-sdk-core/resources/collection.rb
+      #   - each(&block)
+      # -->
+      # @return [Enumerator<Band>]
+      #
       def each: () -> Enumerator[T, untyped]
               | () { (T) -> untyped } -> Enumerator[T, untyped]
+
+      # <!--
+      #   rdoc-file=gems/aws-sdk-core/lib/aws-sdk-core/resources/collection.rb
+      #   - size()
+      # -->
+      # @return [Integer,nil]
+      #     Returns the size of this collection if known, returns `nil` when
+      #     an API call is necessary to enumerate items in this collection.
+      #
       def size: () -> Integer?
+
+      # <!--
+      #   rdoc-file=gems/aws-sdk-core/lib/aws-sdk-core/resources/collection.rb
+      #   - length()
+      # -->
+      #
       alias length size
+
+      # <!--
+      #   rdoc-file=gems/aws-sdk-core/lib/aws-sdk-core/resources/collection.rb
+      #   - first(count = nil)
+      # -->
+      # @param [Integer] count @return [Resource, Collection]
+      #
       def first: () -> T?
                | (Integer) -> self
+
+      # <!--
+      #   rdoc-file=gems/aws-sdk-core/lib/aws-sdk-core/resources/collection.rb
+      #   - limit(limit)
+      # -->
+      # Returns a new collection that will enumerate a limited number of items.
+      #
+      #     collection.limit(10).each do |band|
+      #       # yields at most 10 times
+      #     end
+      #
+      # @return [Collection] @param [Integer] limit
+      #
       def limit: (Integer) -> self
     end
   end
@@ -42,14 +324,25 @@ module Aws
     type waiter_options = { max_attempts: Integer?, delay: Numeric?, before_attempt: (^(Integer attempts) -> void)?, before_wait: (^(Integer attempts, untyped response) -> void)? }
 
     module Errors
+      # <!-- rdoc-file=gems/aws-sdk-core/lib/aws-sdk-core/waiters/errors.rb -->
+      # Raised when a waiter detects a condition where the waiter can never succeed.
+      #
       class WaiterFailed < StandardError
       end
+
       class FailureStateError < WaiterFailed
       end
+
       class TooManyAttemptsError < WaiterFailed
       end
+
       class UnexpectedError < WaiterFailed
       end
+
+      # <!-- rdoc-file=gems/aws-sdk-core/lib/aws-sdk-core/waiters/errors.rb -->
+      # Raised when attempting to get a waiter by name and the waiter has not been
+      # defined.
+      #
       class NoSuchWaiterError < ArgumentError
       end
     end