aws-sdk-core 2.11.394 → 3.75.0

data/lib/aws-sdk-core/api/docs/operation_documenter.rb

@@ -1,151 +0,0 @@
-module Aws
-  module Api
-    module Docs
-      class OperationDocumenter
-
-        include Seahorse::Model
-        include Utils
-
-        def initialize(service_name, namespace, uid)
-          @service_name = service_name
-          @namespace = namespace
-          @optname = 'options'
-          @uid = uid
-        end
-
-        # @param [Symbol] method_name
-        # @param [Seahorse::Model::Opeation] operation
-        def document(method_name, operation)
-          m = YARD::CodeObjects::MethodObject.new(@namespace, method_name)
-          m.group = 'API Operations'
-          m.scope = :instance
-          m.parameters << [@optname, '{}']
-          m.docstring = operation.documentation
-          tags(method_name, operation).each do |tag|
-            m.add_tag(tag)
-          end
-        end
-
-        private
-
-        def tags(method_name, operation)
-          tags = []
-          tags += param_tags(method_name, operation)
-          tags += option_tags(method_name, operation)
-          tags += return_tags(method_name, operation)
-          tags += example_tags(method_name, operation)
-          tags += see_also_tags(method_name, operation)
-        end
-
-        def param_tags(method_name, operation)
-          []
-        end
-
-        def option_tags(method_name, operation)
-          operation_input_ref(operation).shape.members.map do |name, ref|
-            req = ref.required ? 'required,' : ''
-            type = input_type(ref)
-            docstring = "@option #{@optname} [#{req}#{type}] :#{name}\n"
-            docstring << "\n\n This parameter will be auto-filled on your behalf"\
-              " with a random UUIDv4 when no value is provided.\n" if ref['idempotencyToken']
-            docstring << "\n\n SDK automatically handles json encoding and base64 encoding"\
-              " for you when the required value (Hash, Array, etc.) is provided according to the description.\n" if ref['jsonvalue']
-            docstring += ref.documentation.to_s.lines.map { |line| "  #{line}" }.join
-            tag(docstring)
-          end
-        end
-
-        def return_tags(method_name, operation)
-          resp = '{Seahorse::Client::Response response}'
-          if operation.output && operation.output.shape.members.count > 0
-            rtype = output_type(operation.output)
-            returns = "[#{rtype}] Returns a #{resp} object which responds to "
-            returns << "the following methods:\n\n"
-            operation.output.shape.members.each do |mname, mref|
-              mtype = output_type(mref, true).gsub(/</, '&lt;').gsub(/>/, '&gt;')
-              returns << "  * {#{rtype}##{mname} ##{mname}} => #{mtype}\n"
-            end
-          else
-            returns = "[Struct] Returns an empty #{resp}."
-          end
-          [tag("@return #{returns}")]
-        end
-
-        def example_tags(method_name, operation)
-          shared_examples(method_name, operation) +
-          examples_from_disk(method_name, operation) +
-          [
-            request_syntax_example(method_name, operation),
-            response_structure_example(method_name, operation),
-          ].compact
-        end
-
-        def shared_examples(method_name, operation)
-          if operation['examples']
-            operation['examples'].map do |example|
-              shared_example(example, method_name, operation)
-            end.compact
-          else
-            []
-          end
-        end
-
-        def shared_example(json_ex, method_name, operation)
-          begin # disable broken examples
-            input_comments = json_ex['comments']['input']
-            input = SharedExample.new(json_ex['input'], method_name, operation, input_comments).to_str_input
-            parts = []
-            parts << "@example Example: #{json_ex['title']}\n\n"
-            parts << "  # #{json_ex['description']}\n\n"
-            parts += input.lines.map { |line| "  " + line }
-            if json_ex['output']
-              output_comments = json_ex['comments']['output']
-              output = SharedExample.new(json_ex['output'], method_name, operation, output_comments).to_str_output
-              parts << "\n\n  # resp.to_h outputs the following:\n"
-              parts += output.lines.map { |line| "  " + line }
-            end
-            tag(parts.join)
-          rescue
-            nil
-          end
-        end
-
-        def examples_from_disk(method_name, operation)
-          dir = "doc-src/examples/#{@service_name.downcase}/client/#{method_name}/*.rb"
-          Dir.glob(dir).map do |path|
-            title = File.basename(path).split(/\./).first
-            title = title.sub(/^\d+_/, '').gsub(/_/, ' ')
-            title = title[0].upcase + title[1..-1]
-            tag("@example #{title}\n\n    " + File.read(path).lines.join('    '))
-          end
-        end
-
-        def request_syntax_example(method_name, operation)
-          example = RequestSyntaxExample.new(method_name, operation).to_str
-          parts = []
-          parts << "@example Request syntax with placeholder values\n\n"
-          parts += example.lines.map { |line| "  " + line }
-          tag(parts.join)
-        end
-
-        def response_structure_example(method_name, operation)
-          if example = ResponseStructureExample.new(method_name, operation).to_str
-            parts = []
-            parts << "@example Response structure\n\n"
-            parts += example.lines.map { |line| "  " + line }
-            tag(parts.join)
-          end
-        end
-
-        def see_also_tags(method_name, operation)
-          if Crosslink.taggable?(@uid)
-            [tag(Crosslink.tag_string(@uid, operation.name))]
-          else
-            []
-          end
-        end
-
-      end
-    end
-  end
-end

data/lib/aws-sdk-core/api/docs/param_formatter.rb

@@ -1,163 +0,0 @@
-module Aws
-  module Api
-    module Docs
-      class ParamFormatter
-
-        include Utils
-        include Seahorse::Model::Shapes
-
-        def initialize(shape_ref)
-          @shape_ref = shape_ref
-          @recursive_shapes = compute_recursive_shapes(@shape_ref)
-        end
-
-        def format
-          if @shape_ref && @shape_ref.shape.member_names.count > 0
-            ref_value(@shape_ref, '', [])
-          else
-            ''
-          end
-        end
-
-        private
-
-        def ref_value(ref, i, visited)
-          if visited.include?(ref.shape)
-            return "{\n#{i}  # recursive #{ref.shape.name}\n#{i}}"
-          else
-            visited  = visited + [ref.shape]
-          end
-          case ref.shape
-          when StructureShape
-            if ref.shape.name == 'AttributeValue'
-              '"value"'
-            else
-              struct(ref, i, visited)
-            end
-          when BlobShape
-            if ref[:response_target]
-              '"/path/to/file"'
-            elsif ref[:streaming]
-              'source_file'
-            else
-              '"data"'
-            end
-          when ListShape then list(ref, i, visited)
-          when MapShape then map(ref, i, visited)
-          when BooleanShape then "false"
-          when IntegerShape then '1'
-          when FloatShape then '1.0'
-          when StringShape then string(ref)
-          when TimestampShape then 'Time.now'
-          else raise "unsupported shape #{ref.shape.class.name}"
-          end
-        end
-
-        def struct(ref, i, visited)
-          lines = ['{']
-          ref.shape.members.each do |member_name, member_ref|
-            lines << struct_member(member_name, member_ref, i, visited)
-          end
-          lines << "#{i}}"
-          lines.join("\n")
-        end
-
-        def struct_member(member_name, member_ref, i, visited)
-          entry = "#{i}  #{member_name}: #{ref_value(member_ref, i + '  ', visited)},"
-          apply_comments(member_ref, entry)
-        end
-
-        def list(ref, i, visited)
-          if complex?(ref.shape.member)
-            complex_list(ref.shape.member, i, visited)
-          else
-            scalar_list(ref.shape.member, i, visited)
-          end
-        end
-
-        def scalar_list(ref, i, visited)
-          "[#{ref_value(ref, i, visited)}]"
-        end
-
-        def complex_list(ref, i, visited)
-          "[\n#{i}  #{ref_value(ref, i + '  ', visited)},\n#{i}]"
-        end
-
-        def map(ref, i, visited)
-          key = string(ref.shape.key)
-          value = ref_value(ref.shape.value, i + '  ', visited)
-          "{\n#{i}  #{key} => #{value},#{comments(ref.shape.value)}\n#{i}}"
-        end
-
-        def string(ref)
-          if ref.shape.enum
-            ref.shape.enum.first.inspect
-          elsif ref.shape.name
-            ref.shape.name.inspect
-          else
-            '"string"'
-          end
-        end
-
-        def apply_comments(ref, text)
-          lines = text.lines.to_a
-          if lines[0].match(/\n$/)
-            lines[0] = lines[0].sub(/\n$/, comments(ref) + "\n")
-          else
-            lines[0] += comments(ref)
-          end
-          lines.join
-        end
-
-        def comments(ref)
-          comments = []
-          if ref[:response_target]
-            comments << 'where to write response data, file path, or IO object'
-          end
-          if ref[:streaming]
-            comments << 'file/IO object, or string data'
-          end
-          if ref.required
-            comments << 'required'
-          end
-          if enum = enum_values(ref)
-            comments << "accepts #{enum.to_a.join(', ')}"
-          end
-          if ddb_av?(ref)
-            comments << 'value <Hash,Array,String,Numeric,Boolean,IO,Set,nil>'
-          end
-          comments == [] ? '' : " # #{comments.join(', ')}"
-        end
-
-        def recursive?(ref)
-          @recursive_shapes.include?(ref.shape)
-        end
-
-        def enum_values(ref)
-          case ref.shape
-          when ListShape then enum_values(ref.shape.member)
-          when StringShape then ref.shape.enum
-          else nil
-          end
-        end
-
-        def complex?(ref)
-          if StructureShape === ref.shape
-            !ddb_av?(ref)
-          else
-            ListShape === ref.shape || MapShape === ref.shape
-          end
-        end
-
-        def ddb_av?(ref)
-          case ref.shape
-          when ListShape then ddb_av?(ref.shape.member)
-          when StructureShape then ref.shape.name == 'AttributeValue'
-          else false
-          end
-        end
-
-      end
-    end
-  end
-end

data/lib/aws-sdk-core/api/docs/request_syntax_example.rb

@@ -1,22 +0,0 @@
-module Aws
-  module Api
-    module Docs
-      class RequestSyntaxExample
-
-        include Utils
-        include Seahorse::Model::Shapes
-
-        def initialize(method_name, operation)
-          @method_name = method_name
-          @operation = operation
-        end
-
-        def to_str
-          params = ParamFormatter.new(operation_input_ref(@operation))
-          "resp = client.#{@method_name}(#{params.format})"
-        end
-
-      end
-    end
-  end
-end

data/lib/aws-sdk-core/api/docs/response_structure_example.rb

@@ -1,91 +0,0 @@
-module Aws
-  module Api
-    module Docs
-      class ResponseStructureExample
-
-        include Utils
-        include Seahorse::Model::Shapes
-
-        def initialize(method_name, operation)
-          @method_name = method_name
-          @operation = operation
-          @recursive_shapes = compute_recursive_shapes(@operation.output)
-        end
-
-        def to_str
-          if @operation.output
-            lines = entry(@operation.output, "resp", [])
-            lines.empty? ? nil : lines.join("\n")
-          else
-            nil
-          end
-        end
-
-        private
-
-        def structure(ref, context, visited)
-          lines = []
-          ref.shape.members.each do |member_name, member_ref|
-            lines += entry(member_ref, "#{context}.#{member_name}", visited)
-          end
-          lines
-        end
-
-        def list(ref, context, visited)
-          lines = []
-          lines << "#{context} #=> Array"
-          lines += entry(ref.shape.member, "#{context}[0]", visited)
-          lines
-        end
-
-        def map(ref, context, visited)
-          lines = []
-          lines << "#{context} #=> Hash"
-          lines += entry(ref.shape.value, "#{context}[#{map_key(ref)}]", visited)
-          lines
-        end
-
-        def map_key(ref)
-          (ref.shape.key.shape.name || 'string').inspect
-        end
-
-        def entry(ref, context, visited)
-          if ref.shape.name == 'AttributeValue'
-            return ["#{context} #=> <Hash,Array,String,Numeric,Boolean,IO,Set,nil>"]
-          elsif visited.include?(ref.shape)
-            return ["#{context} #=> Types::#{ref.shape.name}"]
-          else
-            visited  = visited + [ref.shape]
-          end
-          case ref.shape
-          when StructureShape then structure(ref, context, visited)
-          when ListShape then list(ref, context, visited)
-          when MapShape then map(ref, context, visited)
-          else ["#{context} #=> #{value(ref)}"]
-          end
-        end
-
-        def value(ref)
-          case ref.shape
-          when StringShape then string(ref)
-          when IntegerShape then 'Integer'
-          when FloatShape then 'Float'
-          when BooleanShape then 'true/false'
-          when BlobShape then 'IO'
-          when TimestampShape then 'Time'
-          else raise "unhandled shape type #{ref.shape.class.name}"
-          end
-        end
-
-        def string(ref)
-          if ref.shape.enum
-            "String, one of #{ref.shape.enum.map(&:inspect).join(', ')}"
-          else
-            'String'
-          end
-        end
-
-      end
-    end
-  end
-end

data/lib/aws-sdk-core/api/docs/shared_example.rb

@@ -1,100 +0,0 @@
-module Aws
-  module Api
-    module Docs
-      class SharedExample
-
-        include Utils
-        include Seahorse::Model::Shapes
-
-        def initialize(params, method_name, operation, comments)
-          @params = params
-          @method_name = method_name
-          @operation = operation
-          @comments = comments
-          @params ||= {}
-        end
-
-        def to_str_input
-          lines = structure(@params, @operation.input, "", [])
-          params = lines.join("\n")
-          "resp = client.#{@method_name}(#{params})"
-        end
-
-        def to_str_output
-          lines = structure(@params, @operation.output, "", [])
-          params = lines.join("\n")
-          "#{params}"
-        end
-
-        private
-
-        def entry(json, ref, indent, path)
-          case ref.shape
-          when StructureShape then structure(json, ref, indent, path)
-          when MapShape then map(json, ref, indent, path)
-          when ListShape then list(json, ref, indent, path)
-          when TimestampShape then "Time.parse(#{json.inspect})"
-          when StringShape, BlobShape then json.inspect
-          else json
-          end
-        end
-
-        def structure(json, ref, indent, path)
-          lines = ["{"]
-          json.each do |key, val|
-            path << ".#{key}"
-            sc_key = Seahorse::Util.underscore(key)
-            shape_val = entry(val, ref.shape.member(sc_key), "#{indent}  ", path)
-            if shape_val.is_a?(Array)
-              shape_val = shape_val.join("\n")
-            end
-            lines << "#{indent}  #{sc_key}: #{shape_val}, #{apply_comments(path)}"
-            path.pop
-          end
-          lines << "#{indent}}"
-          lines
-        end
-
-        def map(json, ref, indent, path)
-          lines = ["{"]
-          json.each do |key, val|
-            path << ".#{key}"
-            shape_val = entry(val, ref.shape.value, "#{indent}  ", path)
-            if shape_val.is_a?(Array)
-              shape_val = shape_val.join("\n")
-            end
-            lines << "#{indent}  \"#{key}\" => #{shape_val}, #{apply_comments(path)}"
-            path.pop
-          end
-          lines << "#{indent}}"
-          lines
-        end
-
-        def list(json, ref, indent, path)
-          lines = ["["]
-          json.each_with_index do |member, index|
-            path << "[#{index}]"
-            shape_val = entry(member, ref.shape.member, "#{indent}  ", path)
-            if shape_val.is_a?(Array)
-              shape_val = shape_val.join("\n")
-            end
-            lines << "#{indent}  #{shape_val}, #{apply_comments(path)}"
-            path.pop
-          end
-          lines << "#{indent}]"
-          lines
-        end
-
-        def apply_comments(path)
-          key = path.join().sub(/^\./, '')
-          if @comments && @comments[key]
-            "# #{@comments[key]}"
-          else
-            ""
-          end
-        end
-
-      end
-    end
-  end
-end