aws-sdk-resources 2.0.0.pre

data/lib/aws-sdk-resources/documenter/data_operation_documenter.rb

@@ -0,0 +1,47 @@
+module Aws
+  module Resources
+    class Documenter
+      class DataOperationDocumenter < BaseOperationDocumenter
+
+        def docstring
+          if plural?
+            super + " Calls {#{called_operation}}, returning an array of {#{path_type}} objects."
+          else
+            super + " Calls {#{called_operation}}, returning a #{return_type.first}."
+          end
+        end
+
+        def return_message
+          if plural? && structure?
+            "an array of {Structure structures} with the following memers:\n" + data_members
+          elsif structure?
+            "a {Structure} with the following members:\n" + data_members
+          else
+            ''
+          end
+        end
+
+        def data_members
+          "\n" + path_shape.member_names.map{ |n| "\n* `#{n}`" }.join("\n")
+        end
+
+        def return_type
+          if plural?
+            ["Array<#{path_type}>"]
+          else
+            [path_type]
+          end
+        end
+
+        def plural?
+          !!@operation.path.match(/\[/)
+        end
+
+        def structure?
+          Seahorse::Model::Shapes::Structure === path_shape
+        end
+
+      end
+    end
+  end
+end

data/lib/aws-sdk-resources/documenter/enumerate_data_operation_documenter.rb

@@ -0,0 +1,50 @@
+module Aws
+  module Resources
+    class Documenter
+      class EnumerateDataOperationDocumenter < BaseOperationDocumenter
+
+        def docstring
+          super + ' ' + <<-DOCSTRING.lstrip
+Returns an enumerator that yields #{operation_name.gsub('_', ' ')}.
+No API requests are made until you call an enumerable method.
+{#{called_operation}} will be called multiple times until all results
+have been yielded.
+          DOCSTRING
+        end
+
+        def return_type
+          ["Enumerator<#{path_type}>"]
+        end
+
+        def return_message
+          msg = "Returns an enumerator that yields #{operation_name.gsub('_', ' ')}."
+          msg << data_members
+          msg
+        end
+
+        def data_members
+          if path_shape.type == 'structure'
+            msg = "\nEnumerated values have the following properties:\n"
+            path_shape.member_names.each do |name|
+              msg << "\n* `#{name}`"
+            end
+            msg
+          else
+            ''
+          end
+        end
+
+        def example_tags
+          tag = <<-EXAMPLE.strip
+@example Enumerate all #{operation_name}
+  #{variable_name}.#{operation_name}.each do |data|
+    # ...
+  end
+          EXAMPLE
+          YARD::DocstringParser.new.parse(tag).to_docstring.tags
+        end
+
+      end
+    end
+  end
+end

data/lib/aws-sdk-resources/documenter/enumerate_resource_operation_documenter.rb

@@ -0,0 +1,69 @@
+module Aws
+  module Resources
+    class Documenter
+      class EnumerateResourceOperationDocumenter < BaseOperationDocumenter
+
+        def docstring
+          super + ' ' +<<-DOCSTRING.lstrip
+Returns a {Resources::Collection Collection} of {#{target_resource_class_name}}
+resources. No API requests are made until you call an enumerable method on the
+collection. {#{called_operation}} will be called multiple times until every
+{#{target_resource_class_name}} has been yielded. 
+          DOCSTRING
+        end
+
+        def return_type
+          ["Collection<#{target_resource_class_name}>"]
+        end
+
+        def return_message
+          "a {Aws::Resources::Collection Collection} of {#{target_resource_class_name}} resource objects."
+        end
+
+        def example_tags
+          tags = []
+          tags << enumerate_example
+          tags << enumerate_with_limit_example
+          tags << batch_examples if target_resource_batches?
+          YARD::DocstringParser.new.parse(tags.join("\n")).to_docstring.tags
+        end
+
+        def enumerate_example
+          return <<EXAMPLE
+@example Enumerating {#{target_resource_class_name}} resources.
+  #{variable_name}.#{@operation_name}.each do |#{target_resource_class_name.downcase}|
+    # yields each #{target_resource_class_name.downcase}
+  end
+EXAMPLE
+        end
+
+        def enumerate_with_limit_example
+          return <<EXAMPLE
+@example Enumerating {#{target_resource_class_name}} resources with a limit.
+  #{variable_name}.#{@operation_name}.limit(10).each do |#{target_resource_class_name.downcase}|
+    # yields at most 10 #{@operation_name}
+  end
+EXAMPLE
+        end
+
+        def batch_examples
+          example = "@example Batch operations callable on the returned collection"
+          target_resource_batch_operations.each do |name|
+            example << "\n  #{variable_name}.#{@operation_name}.#{name}"
+          end
+          example
+        end
+
+        def target_resource_batches?
+          target_resource_class.const_defined?(:Batch) &&
+          target_resource_batch_operations.count > 0
+        end
+
+        def target_resource_batch_operations
+          target_resource_class::Batch.operation_names
+        end
+
+      end
+    end
+  end
+end

data/lib/aws-sdk-resources/documenter/operation_documenter.rb

@@ -0,0 +1,43 @@
+module Aws
+  module Resources
+    class Documenter
+      class OperationDocumenter < BaseOperationDocumenter
+
+        def docstring
+          super + " #{return_base_message}"
+        end
+
+        def return_type
+          if returns_data_members
+            ['Structure']
+          else
+            ['void']
+          end
+        end
+
+        def return_message
+          "#{return_base_message} #{returns_data_members}"
+        end
+
+        def return_base_message
+          if returns_data_members
+            "Calls {#{called_operation}}, returning its reponse."
+          end
+        end
+
+        def returns_data_members
+          if response_shape && response_shape.member_names.count > 0
+            msg = "The response data has following properties:\n"
+            response_shape.member_names.each do |name|
+              msg << "\n* `#{name}`"
+            end
+            msg
+          else
+            nil
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/aws-sdk-resources/documenter/reference_operation_documenter.rb

@@ -0,0 +1,102 @@
+module Aws
+  module Resources
+    class Documenter
+      class ReferenceOperationDocumenter < BaseOperationDocumenter
+
+        def docstring
+          docs = []
+          docs << super
+
+          if can_return_nil?
+            docs << return_message
+          elsif argument?
+            msg = "Returns a {#{target_resource_class}} resource with "
+            msg << "the given `#{argument_name}`."
+            docs << msg
+          else
+            docs << "Returns a {#{target_resource_class}} resource."
+          end
+
+          if data_member && resource_class.load_operation
+            load_method = resource_class.load_operation.request.method_name
+            msg = "Calling this method will call {Client##{load_method}} "
+            msg << "unless the resource is already {#data_loaded? loaded}. "
+            msg << "No additional API requests are made."
+            docs << msg
+          else
+            msg = "Calling this method will **not** make an API request."
+            docs << msg
+          end
+
+          docs.join(' ')
+        end
+
+        def return_type
+          if plural?
+            type = ["Array<#{target_resource_class_name}>"]
+          else
+            type = [target_resource_class_name]
+          end
+          type << 'nil' if can_return_nil?
+          type
+        end
+
+        def return_message
+          if can_return_nil?
+            "Returns a {#{target_resource_class_name}} resource, or `nil` " +
+            "if `#data.#{data_member_source}` is `nil`."
+          else
+            "Returns a {#{target_resource_class_name}} resource."
+          end
+        end
+
+        def parameters
+          if argument?
+            [[argument_name, nil]]
+          else
+            []
+          end
+        end
+
+        def tags
+          tags = super
+          if argument?
+            tag = "@param [String] #{argument_name} "
+            tag << "The {#{target_resource_class_name}##{argument_name}} "
+            tag << "identifier."
+            tags += YARD::DocstringParser.new.parse(tag).to_docstring.tags
+          end
+          tags
+        end
+
+        def plural?
+          @operation.builder.plural?
+        end
+
+        def argument?
+          @operation.arity > 0
+        end
+
+        def can_return_nil?
+          data_member
+        end
+
+        def data_member
+          builder.sources.find { |s| BuilderSources::DataMember === s }
+        end
+
+        def data_member_source
+          data_member.source
+        end
+
+        def argument_name
+          argument = builder.sources.find do |source|
+            BuilderSources::Argument === source
+          end
+          argument.target.to_s
+        end
+
+      end
+    end
+  end
+end

data/lib/aws-sdk-resources/documenter/resource_operation_documenter.rb

@@ -0,0 +1,65 @@
+module Aws
+  module Resources
+    class Documenter
+      class ResourceOperationDocumenter < BaseOperationDocumenter
+
+        def initialize(*args)
+          super
+          @plural = @operation.builder.plural?
+        end
+
+        # @return [Boolean] Returns `true` if this operation returns an 
+        #   array of resource objects. Returns `false` if this method returns
+        #   a single resource object.
+        attr_reader :plural
+
+        alias plural? plural
+
+        def docstring
+          super + ' ' "#{return_message} Calls {#{called_operation}}."
+        end
+
+        def return_type
+          if plural?
+            ["Array<#{target_resource_class_name}>"]
+          else
+            [target_resource_class_name]
+          end
+        end
+
+        def return_message
+          if plural?
+            "Returns an array of {#{target_resource_class_name}} resources."
+          else
+            "Returns a {#{target_resource_class_name}} resource."
+          end
+        end
+
+        def example_tags
+          id = target_resource_class.identifiers.last.to_s
+          idv = target_resource_class_name.downcase + '-' + id.gsub('_', '-')
+          tag = []
+          tag << "@example Basic usage"
+          tag << "  #{resp_variable} = #{variable_name}.#{operation_name}(params)"
+          if plural?
+            tag << "  #{resp_variable}.map(&:#{id})"
+            tag << "  #=> [#{idv.inspect}, ...]"
+          else
+            tag << "  #{resp_variable}.#{id}"
+            tag << "  #=> #{idv.inspect}"
+          end
+          YARD::DocstringParser.new.parse(tag).to_docstring.tags
+        end
+
+        def resp_variable
+          if plural?
+            target_resource_class_name.downcase + 's'
+          else
+            target_resource_class_name.downcase
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/aws-sdk-resources/documenter/waiter_operation_documenter.rb

@@ -0,0 +1,81 @@
+module Aws
+  module Resources
+    class Documenter
+      class WaiterOperationDocumenter < BaseOperationDocumenter
+
+        def docstring
+          super + ' ' + <<-DOCSTRING.lstrip
+Waits until this #{resource_class_name} is #{state}. This method
+waits by polling {Client##{api_request_name}} until successful. An error is
+raised after a configurable number of failed checks.
+    
+This waiter uses the following defaults:
+
+| Configuration   | Default                |
+|-----------------|------------------------|
+| `#interval`     | #{waiter.interval}     |
+| `#max_attempts` | #{waiter.max_attempts} |
+
+You can modify defaults and register callbacks by passing a block argument.
+@yieldparam [Waiters::Waiter] waiter
+@raise [Waiters::Errors::WaiterFailed]
+@see Client#wait_until
+          DOCSTRING
+        end
+
+        def return_type
+          [resource_class_name]
+        end
+
+        def return_message
+          if @operation.path
+            "Returns a copy of this #{resource_class_name} with loaded data."
+          else
+            "Returns a copy of this #{resource_class_name} that is not loaded."
+          end
+        end
+
+        def state
+          operation_name.to_s.sub('wait_until_', '')
+        end
+
+        def waiter
+          @resource_class.client_class.waiters.waiter(@operation.waiter_name)
+        end
+
+        def api_request
+          @resource_class.client_class.api.operation(api_request_name)
+        end
+
+        def api_request_params
+          @operation.params
+        end
+
+        def api_request_name
+          waiter.send(:operation_name)
+        end
+
+        def option_tags
+          []
+        end
+
+        def example_tags
+          tag = <<-EXAMPLE.strip
+@example Basic usage
+  #{variable_name}.#{operation_name}
+
+@example Modify default configuration
+  #{variable_name}.#{operation_name} do |w|
+     w.interval = 10
+     w.max_attempts = 100
+     w.before_attempt { |count| ... }
+     w.before_wait do { |count, prev_resp| ... }
+  end
+          EXAMPLE
+          YARD::DocstringParser.new.parse(tag).to_docstring.tags
+        end
+
+      end
+    end
+  end
+end