aws-sdk-code-generator 0.1.0.pre → 0.2.0.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: cd7b6eb0cfae166558e734fdb8e7c9236f7f14d6
-  data.tar.gz: 8cad3f3e2213a13d558259216831b08e1e4d5323
+SHA256:
+  metadata.gz: 4894f20ce7d85b716b2c70eb94ab224ae37262f9b325fec17fe45529cd0cf2fa
+  data.tar.gz: 5c0547128fce67627df4e291d97b6fd9a05eb7cd8e09431ba3ca5594dc5c5192
 SHA512:
-  metadata.gz: c970544cd6c87e3794260f4dda931f717c9e7ef9dfb43693b35c0d22f0a3b1ec850b3ff281b7e9e825591905a2a45b19168337521c8039c2e648db3e66b1d525
-  data.tar.gz: 6a927656fc80f7df13cc27c03f1675a81fb3f000bcec4b6fb3ba6d672ad1e37a74296ccaff8b37137e3ce4912780bf1a1818f4b7c03e13ca3b8781f9a7375ade
+  metadata.gz: 7857e3fd7e22f68d17cd4c9cff65e9d80f9e8e0bd526b2c4395bbf2d9f2f215f83694a56179844b46d7f9e302f2fb4eb90dbb810b182e4f001428ba0e3ba9fa5
+  data.tar.gz: 7c41c3cac485f1a10305f987db7861051d32fcd9f34eac72f32ec1ec0da9e157c5c00ddb302772d5ff8affc9eb8b51b1213492751084758a31fd6b40a9aa8714

data/lib/aws-sdk-code-generator.rb

@@ -1,91 +1,84 @@
+# frozen_string_literal: true
+
+require_relative 'aws-sdk-code-generator/api'
 require_relative 'aws-sdk-code-generator/apply_docs'
+require_relative 'aws-sdk-code-generator/client_constructor'
+require_relative 'aws-sdk-code-generator/client_operation_documentation'
+require_relative 'aws-sdk-code-generator/client_operation_list'
+require_relative 'aws-sdk-code-generator/error_list'
+require_relative 'aws-sdk-code-generator/client_response_structure_example'
+require_relative 'aws-sdk-code-generator/crosslink'
+require_relative 'aws-sdk-code-generator/docstring'
+require_relative 'aws-sdk-code-generator/hash_formatter'
 require_relative 'aws-sdk-code-generator/helper'
+require_relative 'aws-sdk-code-generator/plugin_list'
+require_relative 'aws-sdk-code-generator/resource_action'
+require_relative 'aws-sdk-code-generator/resource_action_code'
+require_relative 'aws-sdk-code-generator/resource_association'
+require_relative 'aws-sdk-code-generator/resource_attribute'
+require_relative 'aws-sdk-code-generator/resource_batch_action'
+require_relative 'aws-sdk-code-generator/resource_batch_action_code'
+require_relative 'aws-sdk-code-generator/resource_batch_action_documentation'
+require_relative 'aws-sdk-code-generator/resource_batch_builder'
+require_relative 'aws-sdk-code-generator/resource_builder'
+require_relative 'aws-sdk-code-generator/resource_client_request'
+require_relative 'aws-sdk-code-generator/resource_client_request_documentation'
+require_relative 'aws-sdk-code-generator/resource_client_request_params'
+require_relative 'aws-sdk-code-generator/resource_data_method'
+require_relative 'aws-sdk-code-generator/resource_has_association'
+require_relative 'aws-sdk-code-generator/resource_has_many_association'
+require_relative 'aws-sdk-code-generator/resource_has_many_association_code'
+require_relative 'aws-sdk-code-generator/resource_identifier'
+require_relative 'aws-sdk-code-generator/resource_identifiers_method'
+require_relative 'aws-sdk-code-generator/resource_load_method'
+require_relative 'aws-sdk-code-generator/resource_method'
+require_relative 'aws-sdk-code-generator/resource_skip_params'
+require_relative 'aws-sdk-code-generator/resource_value_source'
+require_relative 'aws-sdk-code-generator/resource_waiter'
 require_relative 'aws-sdk-code-generator/service'
+require_relative 'aws-sdk-code-generator/shared_example'
+require_relative 'aws-sdk-code-generator/eventstream_example'
+require_relative 'aws-sdk-code-generator/syntax_example'
+require_relative 'aws-sdk-code-generator/syntax_example_hash'
 require_relative 'aws-sdk-code-generator/underscore'
 require_relative 'aws-sdk-code-generator/view'
-
-require_relative 'aws-sdk-code-generator/code_builder'
-require_relative 'aws-sdk-code-generator/gem_builder'
-
-# views
+require_relative 'aws-sdk-code-generator/views/client_api_module'
+require_relative 'aws-sdk-code-generator/views/client_class'
+require_relative 'aws-sdk-code-generator/views/async_client_class'
+require_relative 'aws-sdk-code-generator/views/docstring'
+require_relative 'aws-sdk-code-generator/views/errors_module'
 require_relative 'aws-sdk-code-generator/views/features/env'
 require_relative 'aws-sdk-code-generator/views/features/step_definitions'
+require_relative 'aws-sdk-code-generator/views/features/smoke_step_definitions'
+require_relative 'aws-sdk-code-generator/views/features/smoke'
 require_relative 'aws-sdk-code-generator/views/gemspec'
+require_relative 'aws-sdk-code-generator/views/resource_class'
+require_relative 'aws-sdk-code-generator/views/root_resource_class'
 require_relative 'aws-sdk-code-generator/views/service_module'
 require_relative 'aws-sdk-code-generator/views/spec/spec_helper'
+require_relative 'aws-sdk-code-generator/views/types_module'
+require_relative 'aws-sdk-code-generator/views/event_streams_module'
+require_relative 'aws-sdk-code-generator/views/authorizer_class'
+require_relative 'aws-sdk-code-generator/views/apig_endpoint_class'
+require_relative 'aws-sdk-code-generator/views/apig_readme'
 require_relative 'aws-sdk-code-generator/views/version'
+require_relative 'aws-sdk-code-generator/views/waiters_module'
+require_relative 'aws-sdk-code-generator/waiter'
+require_relative 'aws-sdk-code-generator/yard_option_tag'
 
-module AwsSdkCodeGenerator
-
-  autoload :Errors, 'aws-sdk-code-generator/errors'
-  autoload :HashFormatter, 'aws-sdk-code-generator/hash_formatter'
-  autoload :Helper, 'aws-sdk-code-generator/helper'
-
-  module Dsl
-    autoload :AccessControlStatement, 'aws-sdk-code-generator/dsl/access_control_statement'
-    autoload :AutoloadStatement, 'aws-sdk-code-generator/dsl/autoload_statement'
-    autoload :AttributeAccessor, 'aws-sdk-code-generator/dsl/attribute_accessor'
-    autoload :AttributeReader, 'aws-sdk-code-generator/dsl/attribute_reader'
-    autoload :AttributeWriter, 'aws-sdk-code-generator/dsl/attribute_writer'
-    autoload :BlockParam, 'aws-sdk-code-generator/dsl/block_param'
-    autoload :Class, 'aws-sdk-code-generator/dsl/class'
-    autoload :CodeLiteral, 'aws-sdk-code-generator/dsl/code_literal'
-    autoload :CodeObject, 'aws-sdk-code-generator/dsl/code_object'
-    autoload :Docstring, 'aws-sdk-code-generator/dsl/docstring'
-    autoload :Eigenclass, 'aws-sdk-code-generator/dsl/eigenclass'
-    autoload :ExtendStatement, 'aws-sdk-code-generator/dsl/extend_statement'
-    autoload :IncludeStatement, 'aws-sdk-code-generator/dsl/include_statement'
-    autoload :Main, 'aws-sdk-code-generator/dsl/main'
-    autoload :Method, 'aws-sdk-code-generator/dsl/method'
-    autoload :Module, 'aws-sdk-code-generator/dsl/module'
-    autoload :OptionTag, 'aws-sdk-code-generator/dsl/option_tag'
-    autoload :Param, 'aws-sdk-code-generator/dsl/param'
-    autoload :ParamList,  'aws-sdk-code-generator/dsl/param_list'
-    autoload :ReturnTag, 'aws-sdk-code-generator/dsl/return_tag'
-    autoload :TagDocstring, 'aws-sdk-code-generator/dsl/tag_docstring'
-    autoload :TagDefault, 'aws-sdk-code-generator/dsl/tag_default'
-    autoload :TagType, 'aws-sdk-code-generator/dsl/tag_type'
-  end
+# Public interfaces
+require_relative 'aws-sdk-code-generator/code_builder'
+require_relative 'aws-sdk-code-generator/gem_builder'
 
-  module Generators
-    autoload :ClientApiModule, 'aws-sdk-code-generator/generators/client_api_module'
-    autoload :ClientClass, 'aws-sdk-code-generator/generators/client_class'
-    autoload :ClientOperationDocumentation, 'aws-sdk-code-generator/generators/client_operation_documentation'
-    autoload :ErrorsModule, 'aws-sdk-code-generator/generators/errors_module'
-    autoload :TypesModule, 'aws-sdk-code-generator/generators/types_module'
-    autoload :RootResourceClass, 'aws-sdk-code-generator/generators/root_resource_class'
-    autoload :ResourceClass, 'aws-sdk-code-generator/generators/resource_class'
-    autoload :ResponseStructureExample, 'aws-sdk-code-generator/generators/response_structure_example'
-    autoload :ServiceDocumentation, 'aws-sdk-code-generator/generators/service_documentation'
-    autoload :SharedExample, 'aws-sdk-code-generator/generators/shared_example'
-    autoload :StructureTypeClass, 'aws-sdk-code-generator/generators/structure_type_class'
-    autoload :SyntaxExample, 'aws-sdk-code-generator/generators/syntax_example'
-    autoload :WaiterClass, 'aws-sdk-code-generator/generators/waiter_class'
-    autoload :WaitersModule, 'aws-sdk-code-generator/generators/waiters_module'
+module AwsSdkCodeGenerator
 
-    module Resource
-      autoload :Action, 'aws-sdk-code-generator/generators/resource/action'
-      autoload :BatchBuilder, 'aws-sdk-code-generator/generators/resource/batch_builder'
-      autoload :Builder, 'aws-sdk-code-generator/generators/resource/builder'
-      autoload :ClientGetter,  'aws-sdk-code-generator/generators/resource/client_getter'
-      autoload :ClientRequest,  'aws-sdk-code-generator/generators/resource/client_request'
-      autoload :ClientRequestParams,  'aws-sdk-code-generator/generators/resource/client_request_params'
-      autoload :ClientRequestDocs,  'aws-sdk-code-generator/generators/resource/client_request_docs'
-      autoload :CollectionClass,  'aws-sdk-code-generator/generators/resource/collection_class'
-      autoload :DataMethod, 'aws-sdk-code-generator/generators/resource/data_method'
-      autoload :DataAttributeGetter, 'aws-sdk-code-generator/generators/resource/data_attribute_getter'
-      autoload :DataLoadedMethod, 'aws-sdk-code-generator/generators/resource/data_loaded_method'
-      autoload :ExistsMethod, 'aws-sdk-code-generator/generators/resource/exists_method'
-      autoload :ExtractIdentifierMethod, 'aws-sdk-code-generator/generators/resource/extract_identifier_method'
-      autoload :HasAssociation, 'aws-sdk-code-generator/generators/resource/has_association'
-      autoload :HasManyAssociation, 'aws-sdk-code-generator/generators/resource/has_many_association'
-      autoload :InitializeMethod, 'aws-sdk-code-generator/generators/resource/initialize_method'
-      autoload :IdentifiersMethod, 'aws-sdk-code-generator/generators/resource/identifiers_method'
-      autoload :IdentifierGetter, 'aws-sdk-code-generator/generators/resource/identifier_getter'
-      autoload :LoadMethod, 'aws-sdk-code-generator/generators/resource/load_method'
-      autoload :ValueSource, 'aws-sdk-code-generator/generators/resource/value_source'
-      autoload :WaiterMethod, 'aws-sdk-code-generator/generators/resource/waiter_method'
-    end
-  end
+  GENERATED_SRC_WARNING = <<-WARNING_TXT
+# WARNING ABOUT GENERATED CODE
+#
+# This file is generated. See the contributing guide for more information:
+# https://github.com/aws/aws-sdk-ruby/blob/master/CONTRIBUTING.md
+#
+# WARNING ABOUT GENERATED CODE
+  WARNING_TXT
 
 end

data/lib/aws-sdk-code-generator/api.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module AwsSdkCodeGenerator
+  module Api
+    class << self
+
+      # @param [Hash, String] shape_or_shape_ref
+      # @param [Hash, String] api
+      # @return [String, nil]
+      def docstring(shape_or_shape_ref, api)
+        ref, shape = resolve(shape_or_shape_ref, api)
+        # APIG models, downcase shape name in origin or "__" prefix in origin
+        # code-gen shape name might have been changed (upcased_first/lstrip_prefix/both),
+        # when shape cannot be located with current shape name, try to resolve shape with
+        # (downcase_fist/apig_prefix/both) original names
+        if shape.nil?
+          ref, shape = resolve(AwsSdkCodeGenerator::Helper.downcase_first(shape_or_shape_ref), api)
+          if shape.nil?
+            ref, shape = resolve(AwsSdkCodeGenerator::Helper.apig_prefix(shape_or_shape_ref), api)
+            if shape.nil?
+              ref, shape = resolve(AwsSdkCodeGenerator::Helper.apig_prefix(downcase_first(shape_or_shape_ref)), api)
+            end
+          end
+        end
+        ref['documentation'] || shape['documentation']
+      end
+
+      # @param [Hash, String] shape_or_shape_ref
+      # @param [Hash, String] api
+      # @return [Hash<ShapeRef>, Hash<Shape>]
+      def resolve(shape_or_shape_ref, api)
+        if String === shape_or_shape_ref
+          [{}, api['shapes'][shape_or_shape_ref]]
+        elsif shape_or_shape_ref['type']
+          [{}, shape_or_shape_ref]
+        else
+          [shape_or_shape_ref, api['shapes'][shape_or_shape_ref['shape']]]
+        end
+      end
+
+      # @param [String, Hash] shape_name_or_ref
+      # @return [Hash]
+      def shape(shape_name_or_ref, api)
+        case shape_name_or_ref
+        when Hash then api.fetch('shapes').fetch(shape_name_or_ref.fetch('shape'))
+        when String then api.fetch('shapes').fetch(shape_name_or_ref)
+        end
+      end
+
+      def ruby_input_type(shape_ref, api, options = {})
+        nested = options.fetch(:nested, false)
+        _, shape = resolve(shape_ref, api)
+        case shape['type']
+        when 'byte' then 'Integer<byte>'
+        when 'blob' then 'String, IO'
+        when 'boolean' then 'Boolean'
+        when 'character' then 'String<character>'
+        when 'double' then 'Float'
+        when 'float' then 'Float'
+        when 'integer' then 'Integer'
+        when 'list'
+          if nested
+            "Array"
+          else
+            "Array<#{ruby_input_type(shape['member'], api, nested: true)}>"
+          end
+        when 'long' then 'Integer'
+        when 'map'
+          if nested
+            "Hash"
+          else
+            "Hash<String,#{ruby_input_type(shape['value'], api, nested: true)}>"
+          end
+        when 'string' then 'String'
+        when 'structure' then "Types::#{shape_ref['shape']}"
+        when 'timestamp' then 'Time,DateTime,Date,Integer,String'
+        else
+          raise "unhandled type #{shape.type}.inspect"
+        end
+      end
+
+      def ruby_type(shape_ref, api)
+        _, shape = resolve(shape_ref, api)
+        case shape['type']
+        when 'blob' then streaming?(shape_ref, api) ? 'IO' : 'String'
+        when 'boolean' then 'Boolean'
+        when 'byte' then 'Integer<byte>'
+        when 'character' then 'String<character>'
+        when 'double' then 'Float'
+        when 'float' then 'Float'
+        when 'integer' then 'Integer'
+        when 'list' then "Array<#{ruby_type(shape['member'], api)}>"
+        when 'long' then 'Integer'
+        when 'map' then "Hash<String,#{ruby_type(shape['value'], api)}>"
+        when 'string' then streaming?(shape_ref, api) ? 'IO' : 'String'
+        when 'structure' then "Types::#{shape_ref['shape']}"
+        when 'timestamp' then 'Time'
+        else
+          raise "unhandled type #{shape['type'].inspect}"
+        end
+      end
+
+      # @return [Boolean]
+      def streaming?(shape_or_shape_ref, api)
+        ref, shape = resolve(shape_or_shape_ref, api)
+        ref['streaming'] || shape['streaming'] ||
+          ref['eventstream'] || shape['eventstream']
+      end
+
+      # @return [Boolean]
+      def eventstream?(shape_or_shape_ref, api)
+        ref, shape = resolve(shape_or_shape_ref, api)
+        ref['eventstream'] || shape['eventstream']
+      end
+
+      def plural?(resource)
+        plural = false
+        (resource['identifiers'] || []).each do |i|
+          if i['path'] && i['path'].include?('[]')
+            plural = true
+            break
+          end
+        end
+        plural = true if resource['data'] && resource['data'].include?('[]')
+        plural
+      end
+
+    end
+  end
+end

data/lib/aws-sdk-code-generator/apply_docs.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module AwsSdkCodeGenerator
   class ApplyDocs
 
@@ -17,17 +19,28 @@ module AwsSdkCodeGenerator
     def apply_docs(docs)
       @api['documentation'] = docs['service']
       docs['operations'].each do |name, docstring|
+        next unless @api['operations'][name]
         @api['operations'][name]['documentation'] = docstring
       end
       docs['shapes'].each do |shape_name, shape_docs|
+        next unless @api['shapes'][shape_name]
         @api['shapes'][shape_name]['documentation'] = shape_docs['base']
         shape_docs['refs'].each do |ref, ref_docs|
           ref_shape, ref_member = ref.split('$')
+          next unless @api['shapes'][ref_shape]
           case @api['shapes'][ref_shape]['type']
           when 'structure'
-            @api['shapes'][ref_shape]['members'][ref_member]['documentation'] = ref_docs
+            shape = @api['shapes'][ref_shape]
+            if shape && shape['members']
+              member = shape['members'][ref_member]
+              member['documentation'] = ref_docs if member
+            end
           when 'list', 'map'
-            @api['shapes'][ref_shape][ref_member]['documentation'] = ref_docs
+            shape = @api['shapes'][ref_shape]
+            if shape
+              member = shape[ref_member]
+              member['documentation'] = ref_docs if member
+            end
           end
         end
       end

data/lib/aws-sdk-code-generator/client_constructor.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module AwsSdkCodeGenerator
+  class ClientConstructor
+
+    # @option options [required, PluginList] :plugins
+    def initialize(options)
+      plugin_options = documented_plugin_options(options.fetch(:plugins))
+      documentation = {}
+      plugin_options.each do |option|
+        documentation[option.name] = YardOptionTag.new(
+          name: option.name,
+          required: option.required,
+          ruby_type: option.doc_type,
+          default_value: option.doc_default(options),
+          docstring: option.docstring,
+          indent: "  "
+        ).to_s
+      end
+      @documentation = Docstring.join_docstrings(documentation.values, block_comment: false)
+    end
+
+    # @return [String]
+    attr_reader :documentation
+
+    private
+
+    def documented_plugin_options(plugins)
+      i = 0
+      plugins.map(&:options).flatten.select(&:documented?).sort_by do |opt|
+        # Stable sort, first required options, then sort by name, then if
+        # two plugins of the same name, use an incrementer.
+        # options.fetch(:plugins) will be ordered.
+        [opt.required ? 'a' : 'b', opt.name, i += 1] #, opt.override ? 'b' : 'a']
+      end
+    end
+
+  end
+end

data/lib/aws-sdk-code-generator/client_operation_documentation.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+module AwsSdkCodeGenerator
+  class ClientOperationDocumentation
+
+    # @option options [required, String] :method_name
+    # @option options [required, Hash] :operation
+    # @option options [required, Hash] :api
+    # @option options [Array<Hash>] :examples
+    def initialize(options)
+      @name = options.fetch(:name)
+      @method_name = options.fetch(:method_name)
+      @operation = options.fetch(:operation)
+      @api = options.fetch(:api)
+      @client_examples = options.fetch(:client_examples, [])
+      @examples = options.fetch(:examples)
+      @module_name = options.fetch(:module_name)
+      @async_client = options[:async_client] || false
+      @pager = options[:pager]
+      @waiters = options[:waiters]
+    end
+
+    # @return [String]
+    attr_reader :method_name
+
+    # @return [String]
+    attr_reader :module_name
+
+    # @return [Hash]
+    attr_reader :operation
+
+    # @return [Hash]
+    attr_reader :api
+
+    # @return [Array<Hash>]
+    attr_reader :examples
+
+    # @return [Array<Hash>]
+    attr_reader :client_examples
+
+    # @return [Hash]
+    attr_reader :pager
+
+    # @return [String]
+    def to_str
+      Docstring.join_docstrings([
+        docstring(operation),
+        response_target_tag(operation, api),
+        option_tags(operation, api),
+        return_tag(operation, api),
+        pagination(pager, operation, api),
+        generated_examples(operation, api),
+        eventstream_examples(module_name, method_name, operation, api),
+        shared_examples(examples, operation, api),
+        given_examples(client_examples),
+        @async_client ? async_request_syntax_example(method_name, operation, api)
+        : request_syntax_example(method_name, operation, api),
+        response_structure_example(operation, api),
+        waiters_tag(@waiters),
+        see_also_tag(operation, api),
+      ], block_comment: false)
+    end
+    alias to_s to_str
+
+    private
+
+    def docstring(operation)
+      Docstring.block_comment(
+        Docstring.html_to_markdown(operation['documentation'])
+      )
+    end
+
+    def response_target_tag(operation, api)
+      if output = Api.shape(operation['output'], api)
+        if output['payload'] && output['members'][output['payload']]['streaming']
+          YardOptionTag.new(
+            name: 'response_target',
+            ruby_type: 'String, IO',
+            option_hash_name: 'params',
+            required: false,
+            docstring: 'Where to write response data, file path, or IO object.'
+          ).to_s
+        end
+      end
+    end
+
+    def option_tags(operation, api)
+      if operation['input']
+        shape = Api.shape(operation['input'], api)
+        return if shape['members'].nil?
+        shape['members'].map do |member_name, member_ref|
+          next if member_ref['documented'] === false
+          # input eventstream is not provided by params
+          member_shape = Api.shape(member_ref['shape'], api)
+          next if member_shape['eventstream'] === true
+          docstring = Api.docstring(member_ref, api)
+          if member_ref['idempotencyToken']
+            docstring = docstring.to_s + "<p><b>A suitable default value is auto-generated.** You should normally not need to pass this option.</b></p>"
+          end
+          if member_ref['jsonvalue']
+            docstring = docstring.to_s + "<p><b>SDK automatically handles json encoding and base64 encoding for you when the required value (Hash, Array, etc.) is provided according to the description.</b></p>"
+          end
+          YardOptionTag.new(
+            name: Underscore.underscore(member_name),
+            ruby_type: Api.ruby_input_type(member_ref, api),
+            required: shape.fetch('required', []).include?(member_name),
+            docstring: Docstring.html_to_markdown(docstring),
+            option_hash_name: 'params',
+          ).to_s
+        end
+      else
+        []
+      end
+    end
+
+    def return_tag(operation, api)
+      output = Api.shape(operation['output'], api)
+      if output && output['members'] && output['members'].size > 0
+        shape_name = operation.fetch('output').fetch('shape')
+        type = "Types::#{shape_name}"
+        _, shape = Api.resolve(shape_name, api)
+        # add rest body streaming if qualified
+        unless shape['payload'].nil?
+          _, member_shape = Api.resolve(shape['payload'], api)
+          unless member_shape.nil?
+            member_shape['streaming'] = member_shape['type'] == 'blob' ||
+              member_shape['type'] == 'string'
+          end
+        end
+        methods = shape['members'].map do |member_name, member_ref|
+          member_type = Docstring.escape_html(Api.ruby_type(member_ref, api))
+          method_name = Underscore.underscore(member_name)
+          "#   * {#{type}##{method_name} ##{method_name}} => #{member_type}"
+        end
+        "# @return [#{type}] Returns a {Seahorse::Client::Response response} object which responds to the following methods:\n#\n" + methods.join("\n")
+      else
+        "# @return [Struct] Returns an empty {Seahorse::Client::Response response}."
+      end
+    end
+
+    def pagination(pager, operation, api)
+      return unless pager
+
+      input = Array(pager['input_token'])
+      output = Array(pager['output_token'])
+      tokens = {}
+      input.each.with_index do |key, n|
+        tokens[Underscore.underscore_jmespath(output[n])] = Underscore.underscore_jmespath(key)
+      end
+
+      return if tokens.empty?
+
+      "# The returned {Seahorse::Client::Response response}" \
+      " is a pageable response and is Enumerable. For details on usage see" \
+      " {Aws::PageableResponse PageableResponse}."
+    end
+
+    def shared_examples(examples, operation, api)
+      return if examples.nil? || examples['examples'].nil? || examples['examples'][@name].nil?
+      begin # skip broken/nil examples
+        example_block = []
+        examples['examples'][@name].each do |example|
+          comments = example['comments']
+          input = SharedExample.new(
+            example['input'],
+            method_name,
+            operation,
+            api,
+            (comments.nil? ? '' : comments['input'])).to_str_input
+          parts = []
+          parts << "#\n"
+          parts << "# @example Example: #{example['title']}\n#\n"
+          if example['description'] && example['description'].length > 0
+            parts << "#{Helper.wrap_string(example['description'], 120, "#   # ")}\n#\n"
+          end
+          parts += input.lines.map { |line| "#   " + line }
+          if example['output']
+            output = SharedExample.new(
+              example['output'],
+              method_name,
+              operation,
+              api,
+              (comments.nil? ? '' : comments['output'])).to_str_output
+            parts << "\n#\n#   resp.to_h outputs the following:\n"
+            parts += output.lines.map { |line| "#   " + line }
+          end
+          example_block << parts.join
+        end
+        example_block.join("\n")
+      rescue
+        puts "Invalid example for operation: #{@name}"
+        nil
+      end
+    end
+
+    def generated_examples(operation, api)
+      nil
+    end
+
+    def eventstream_examples(module_name, method_name, operation, api)
+      return unless !!Helper.eventstream_output?(operation, api)
+      EventStreamExample.new(
+        api: api,
+        operation: operation,
+        method_name: method_name,
+        module_name: module_name,
+        receiver: 'client',
+        resp_var: 'resp'
+      ).format
+    end
+
+    def given_examples(client_examples)
+      client_examples.map do |example|
+        name = example[:name]
+        code = example[:code]
+        "# @example #{name}\n" + Docstring.block_comment(code, gap: '   ')
+      end
+    end
+
+    def request_syntax_example(method_name, operation, api)
+      SyntaxExample.new(
+        api: api,
+        shape: Api.shape(operation['input'], api),
+        method_name: method_name,
+        receiver: 'client',
+        resp_var: 'resp',
+      ).format
+    end
+
+    def async_request_syntax_example(method_name, operation, api)
+      SyntaxExample.new(
+        api: api,
+        shape: Api.shape(operation['input'], api),
+        method_name: method_name,
+        receiver: 'async_client',
+        resp_var: 'async_resp',
+        async: true
+      ).format
+    end
+
+    def response_structure_example(operation, api)
+      output = Api.shape(operation['output'], api) if operation['output']
+      if output && output['members'] && output['members'].size > 0
+        Docstring.block_comment(ClientResponseStructureExample.new(
+          shape_ref: operation['output'],
+          api: api
+        ).to_s)
+      end
+    end
+
+    def waiters_tag(waiters)
+      return unless waiters && waiters.size > 0
+
+      waiters_doc = waiters.map do |w|
+        "#   * #{w.name}"
+      end
+      "#\n# The following waiters are defined for this operation (see {Client#wait_until} for detailed usage):\n#\n" + waiters_doc.join("\n")
+    end
+
+    def see_also_tag(operation, api)
+      uid = api['metadata']['uid']
+      if api['metadata']['protocol'] != 'api-gateway' && Crosslink.taggable?(uid)
+        "# " + Crosslink.tag_string(uid, operation['name'])
+      end
+    end
+
+  end
+end