aws-sdk-core 2.4.0 → 3.53.0

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

@@ -1,109 +0,0 @@
-module Aws
-  module Api
-    module Docs
-      class ClientTypeDocumenter
-
-        include Utils
-        include Seahorse::Model
-        include Seahorse::Model::Shapes
-
-        # @param [Yard::CodeObjects::Base] namespace
-        def initialize(namespace)
-          @namespace = namespace
-        end
-
-        # @param [Seahorse::Model::Api] api
-        # @param [Seahorse::Model::Shapes::StructureShape] shape
-        def document(api, shape)
-          yard_class = YARD::CodeObjects::ClassObject.new(@namespace, shape.name)
-          yard_class.superclass = 'Struct'
-          yard_class.docstring = docstring(api, shape)
-          tags(api, shape).each do |tag|
-            yard_class.add_tag(tag)
-          end
-          shape.members.each do |member_name, ref|
-            document_struct_member(yard_class, member_name, ref)
-          end
-        end
-
-        private
-
-        def docstring(api, shape)
-          docs = shape.documentation || ''
-          methods = returned_by(api, shape)
-          unless methods.empty?
-            docs += "<p>Returned by:</p>"
-            docs += "<ul>"
-            docs += methods.map{|m| "<li>{#{m}}</li>" }.join
-            docs += "</ul>"
-          end
-          docs
-        end
-
-        def tags(api, shape)
-          tags = []
-          tags << input_example_tag(api, shape) if input_shape?(api, shape)
-          tags
-        end
-
-        # Returns `true` if the given shape is ever used as input in the api.
-        def input_shape?(haystack, needle, stack = [])
-          if stack.include?(haystack)
-            return false
-          else
-            stack += [haystack]
-          end
-          case haystack
-          when needle
-            return true
-          when Seahorse::Model::Api
-            haystack.operations.each do |_, operation|
-              if operation.input && input_shape?(operation.input.shape, needle, stack)
-                return true
-              end
-            end
-          when StructureShape
-            haystack.members.each do |_, member_ref|
-              if input_shape?(member_ref.shape, needle, stack)
-                return true
-              end
-            end
-          when ListShape
-            return input_shape?(haystack.member.shape, needle, stack)
-          when MapShape
-            return input_shape?(haystack.value.shape, needle, stack)
-          end
-          false
-        end
-
-        def input_example_tag(api, shape)
-          params = ParamFormatter.new(ShapeRef.new(shape: shape))
-          note = "@note When passing #{shape.name} as input to an #{Client} "
-          note << "method, you can use a\n  vanilla Hash:\n\n      "
-          note << params.format.lines.join("      ")
-          tag(note)
-        end
-
-        def returned_by(api, shape)
-          methods = []
-
-          api.metadata['shapes'].each_structure do |struct|
-            struct.members.each do |member_name, member_ref|
-              if member_ref.shape == shape
-                methods << "Types::#{struct.name}##{member_name}"
-              end
-            end
-          end
-
-          api.operations.each do |operation_name, operation|
-            if operation.output && operation.output.shape == shape
-              methods << "Client##{operation_name}"
-            end
-          end
-          methods
-        end
-
-      end
-    end
-  end
-end

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

@@ -1,75 +0,0 @@
-module Aws
-  module Api
-    module Docs
-      class DocstringProvider
-
-        def initialize(docstrings)
-          @docstrings = docstrings
-        end
-
-        # @param [String] operation_name
-        # @return [String,nil]
-        def operation_docs(operation_name)
-          clean(@docstrings['operations'][operation_name])
-        end
-
-        # @param [String] shape_name
-        # @return [String,nil]
-        def shape_docs(shape_name)
-          clean(shape(shape_name)['base'])
-        end
-
-        # @param [String] shape_name
-        # @param [String] target
-        # @return [String,nil]
-        def shape_ref_docs(shape_name, target)
-          if ref_docs = shape(shape_name)['refs'][target]
-            docs = clean(ref_docs)
-            # Running through kramdown to catch unclosed tags that
-            # break the client doc pages, see Aws::RDS::Client
-            # for an example.
-            begin
-              require 'kramdown'
-              Kramdown::Document.new(docs, input: 'html').to_kramdown.strip
-            rescue LoadError
-              docs
-            end
-          else
-            shape_docs(shape_name)
-          end
-        end
-
-        private
-
-        def shape(name)
-          @docstrings['shapes'][name] || { 'base' => nil, 'refs' => {} }
-        end
-
-        def clean(value)
-          if value.nil?
-            ''
-          else
-            value.gsub(/\{(\S+)\}/, '`{\1}`').strip
-          end
-        end
-
-      end
-
-      class NullDocstringProvider
-
-        def operation_docs(operation_name)
-          nil
-        end
-
-        def shape_docs(shape_name)
-          nil
-        end
-
-        def shape_ref_docs(shape_name, target)
-          nil
-        end
-
-      end
-    end
-  end
-end

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

@@ -1,138 +0,0 @@
-module Aws
-  module Api
-    module Docs
-      class OperationDocumenter
-
-        include Seahorse::Model
-        include Utils
-
-        def initialize(service_name, namespace)
-          @service_name = service_name
-          @namespace = namespace
-          @optname = 'options'
-        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 += ref.documentation.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
-          else
-            []
-          end
-        end
-
-        def shared_example(json_ex, method_name, operation)
-          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)
-        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)
-          []
-        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