aws-sdk 2.0.1 → 2.0.5

package/doc-src/templates/api-versions/model_documentor.rb

@@ -0,0 +1,366 @@
+require 'nokogiri'
+
+module Documentor
+  def documentation(rules)
+    docs = rules['documentation'] || ''
+    docs = docs.gsub(/<!--.*?-->/m, '')
+    docs = docs.gsub(/<examples?>.+?<\/examples?>/m, '')
+    docs = docs.gsub(/<\/?note>/m, '')
+    docs = docs.gsub(/\{(\S+)\}/, '`{\1}`')
+    docs = docs.gsub(/\s+/, ' ').strip
+    docs == '' ? nil : docs
+  end
+
+  def method_name(name, downcased = true)
+    name = name.sub(/\d{4}_\d{2}_\d{2}$/, '')
+    downcased ? name[0].downcase + name[1..-1] : name
+  end
+end
+
+class ModelDocumentor
+  include Documentor
+
+  attr_reader :lines
+
+  def initialize(klass, api)
+    api_version = api['metadata']['apiVersion']
+    @lines = []
+    @lines << ''
+    @lines << <<-DOCS.strip
+Constructs a service interface object. Each API operation is exposed as a
+function on service.
+
+### Sending a Request Using #{klass}
+
+```javascript
+var #{klass.downcase} = new AWS.#{klass}();
+#{klass.downcase}.#{find_example_operation(api)}(params, function (err, data) {
+  if (err) console.log(err, err.stack); // an error occurred
+  else     console.log(data);           // successful response
+});
+```
+
+### Locking the API Version
+
+In order to ensure that the #{klass} object uses this specific API, you can
+construct the object by passing the `apiVersion` option to the constructor:
+
+```javascript
+var #{klass.downcase} = new AWS.#{klass}({apiVersion: '#{api_version}'});
+```
+
+You can also set the API version globally in `AWS.config.apiVersions` using
+the **#{klass.downcase}** service identifier:
+
+```javascript
+AWS.config.apiVersions = {
+  #{klass.downcase}: '#{api_version}',
+  // other service API versions
+};
+
+var #{klass.downcase} = new AWS.#{klass}();
+```
+DOCS
+  end
+
+  def find_example_operation(api)
+    list = api['operations'].keys.grep(/describe|list|get/)
+    list = api['operations'].keys if list.size == 0
+    method_name(list.first)
+  end
+end
+
+class MethodDocumentor
+
+  include Documentor
+
+  attr_reader :lines
+
+  def initialize(operation_name, operation, api, klass)
+    desc = documentation(operation)
+    desc ||= "Calls the #{method_name(operation_name, false)} API operation."
+    desc = desc.gsub(/^\s+/, '').strip
+
+    @lines = [desc, '']
+
+    ## @param tags
+
+    @lines << "@param params [Object]"
+    @lines += shapes(api, operation['input']).map {|line| "  " + line }
+
+    ## @example tag
+
+    @lines << "@example Calling the #{method_name(operation_name)} operation"
+    @lines << generate_example(api, klass, method_name(operation_name),
+                operation['input']).split("\n").map {|line| "  " + line }
+    @lines << ""
+
+    ## @callback tag
+
+    @lines << "@callback callback function(err, data)"
+    @lines << "  Called when a response from the service is returned. If a"
+    @lines << "  callback is not supplied, you must call {AWS.Request.send}"
+    @lines << "  on the returned request object to initiate the request."
+    @lines << "  @param err [Error] the error object returned from the request."
+    @lines << "    Set to `null` if the request is successful."
+    @lines << "  @param data [Object] the de-serialized data returned from"
+    @lines << "    the request. Set to `null` if a request error occurs."
+
+    output = shapes(api, operation['output'])
+    output = output.map {|line| "    " + line }
+    if output.size > 0
+      @lines << "    The `data` object has the following properties:"
+      @lines << ""
+      @lines += output
+    end
+
+    ## @return tag
+
+    @lines << "@return [AWS.Request] a handle to the operation request for"
+    @lines << "  subsequent event callback registration."
+
+    if operation['documentation_url']
+      @lines << "@see #{operation['documentation_url']}"
+      @lines << "  #{api['serviceAbbreviation']} Documentation for #{operation_name}"
+    end
+  end
+
+  def shapes(api, rules)
+    rules = api['shapes'][rules['shape']] if rules && rules['shape']
+    if rules and rules['members']
+      rules['members'].map do |name, member_rules|
+        if member_rules['shape']
+          member_rules = api['shapes'][member_rules['shape']].merge(member_rules)
+        end
+        ShapeDocumentor.new(api, member_rules, :name => name).lines
+      end.flatten
+    else
+      []
+    end
+  end
+
+  def generate_example(api, klass, name, input)
+    ExampleShapeVisitor.new(api).example(klass, name, input)
+  end
+
+end
+
+class ExampleShapeVisitor
+  def initialize(api, required_only = false)
+    @api = api
+    @required_only = required_only
+  end
+
+  def example(klass, name, input)
+    lines = []
+    params = traverse(input)
+    params_var = ""
+    if params.strip.length > 0
+      lines << "var params = " + params + ";"
+      params_var = "params, "
+    end
+    lines << "#{klass.downcase}.#{name}(#{params_var}function(err, data) {"
+    lines << "  if (err) console.log(err, err.stack); // an error occurred"
+    lines << "  else     console.log(data);           // successful response"
+    lines << "});"
+    lines.join("\n")
+  end
+
+  def traverse(node, required = false)
+    return "" if node.nil?
+    node = @api['shapes'][node['shape']].merge(node) if node['shape']
+    if (meth = "visit_" + (node['type'] || 'string')) && respond_to?(meth)
+      return send(meth, node, required)
+    end
+    ""
+  end
+
+  def visit_structure(node, required = false)
+    required_map = (node['required'] || []).inject({}) {|h,k| h[k] = true; h }
+    lines = ["{" + (required ? " // required" : "")]
+    node['members'].sort_by {|n, v| [required_map[n] ? -1 : 1, n] }.each_with_index do |(key, value), index|
+      next if @required_only && !required_map[key]
+      value = @api['shapes'][value['shape']].merge(value) if value['shape']
+      lines << "  #{key}: " + indent(traverse(value, required_map[key]), false) +
+        (index + 1 < node['members'].size ? "," : "") +
+        (required_map[key] && !%w(list map structure).include?(value['type']) ?
+          " // required" : "")
+    end
+    lines << "}"
+    lines.join("\n")
+  end
+
+  def visit_list(node, required = false)
+    lines = ["[" + (required ? " // required" : "")]
+    lines << indent(traverse(node['member'])) + ","
+    lines << "  // ... more items ..."
+    lines << "]"
+    lines.join("\n")
+  end
+
+  def visit_map(node, required = false)
+    lines = ["{" + (required ? " // required" : "")]
+    lines << indent("someKey: " + traverse(node['value'])) + ","
+    lines << "  // anotherKey: ..."
+    lines << "}"
+    lines.join("\n")
+  end
+
+  def visit_string(node, required = false)
+    value = node['enum'] ? node['enum'].join(' | ') : 'STRING_VALUE'
+    "'#{value}'"
+  end
+
+  def visit_integer(node, required = false)
+    "0"
+  end
+  alias visit_long visit_integer
+
+  def visit_float(node, required = false)
+    "0.0"
+  end
+  alias visit_double visit_float
+  alias visit_bigdecimal visit_float
+
+  def visit_boolean(node, required = false)
+    "true || false"
+  end
+
+  def visit_base64(node, required = false)
+    "new Buffer('...') || 'STRING_VALUE'"
+  end
+
+  def visit_binary(node, required = false)
+    value = "new Buffer('...') || 'STRING_VALUE'"
+    value += " || streamObject" if node['streaming']
+    value
+  end
+  alias visit_blob visit_binary
+
+  def visit_timestamp(node, required = false)
+    "new Date || 'Wed Dec 31 1969 16:00:00 GMT-0800 (PST)' || 123456789"
+  end
+
+  def indent(text, first_line = true, n = 2)
+    text = text.split(/\r?\n/).map {|l| "#{' ' * n}#{l}" }.join("\n")
+    text = text.sub(/\A\s+/, '') if !first_line
+    text
+  end
+end
+
+class ShapeDocumentor
+  include Documentor
+
+  attr_reader :name
+  attr_reader :rules
+  attr_reader :lines
+  attr_reader :nested_lines
+  attr_reader :prefix
+  attr_reader :type
+
+  def initialize(api, rules, options = {})
+    rules = api['shapes'][rules['shape']].merge(rules) if rules['shape']
+
+    @api = api
+    @rules = rules
+    @name = options[:name]
+    @prefix = options[:prefix] || ''
+    @required = !!options[:required]
+
+    @type =
+      case rules['type']
+      when 'structure' then 'map'
+      when 'list' then 'Array'
+      when 'map' then 'map'
+      when 'string', nil then 'String'
+      when 'integer' then 'Integer'
+      when 'long' then 'Integer'
+      when 'float' then 'Float'
+      when 'double' then 'Float'
+      when 'bigdecimal' then 'Float'
+      when 'boolean' then 'Boolean'
+      when 'base64' then 'Buffer, Typed Array, Blob, String'
+      when 'binary' then 'Buffer, Typed Array, Blob, String'
+      when 'blob' then 'Buffer, Typed Array, Blob, String'
+      when 'timestamp' then 'Date'
+      else raise "unhandled type: #{rules['type']}"
+      end
+
+    # TODO : update this format description once we add streaming uploads
+    @type += ', ReadableStream' if streaming?
+
+    @lines = []
+    @nested_lines = []
+
+    if structure?
+      required_map = (rules['required'] || []).inject({}) {|h,k| h[k] = true; h }
+      rules['members'].each_pair do |name, member_rules|
+        @nested_lines += child_shape(member_rules,
+          :name => name, :required => required_map[name]).lines
+      end
+    end
+
+    if list?
+      child = child_shape(rules['member'] || {}, :prefix => prefix)
+      @type << "<#{child.type}>"
+      @nested_lines += child.nested_lines
+    end
+
+    if map?
+
+      # sanity check, I don't think this should ever raise, but if it
+      # does we will have to document the key shape
+      key_child = child_shape(rules['key'] || {}, :prefix => prefix)
+      raise "unhandled map key type" if key_child.type != 'String'
+
+      child = child_shape(rules['value'] || {}, :prefix => prefix)
+      @type << "<#{child.type}>"
+      @nested_lines += child.nested_lines
+
+    end
+
+    @lines = ["#{prefix}* `#{name}` #{description}"]
+    @lines += @nested_lines
+
+    if rules['enum']
+      @lines << "#{prefix}   Possible values include:"
+      @lines += rules['enum'].map{|v| "#{prefix}   * `#{v.inspect}`" }
+    end
+
+  end
+
+  def streaming?
+    rules['streaming']
+  end
+
+  def structure?
+    rules['type'] == 'structure'
+  end
+
+  def list?
+    rules['type'] == 'list'
+  end
+
+  def map?
+    rules['type'] == 'map'
+  end
+
+  def description
+    text = []
+    if @required
+      text << "&mdash; **required** &mdash; (`#{@type}`)"
+    else
+      text << "&mdash; (`#{@type}`)"
+    end
+    if docs = documentation(rules)
+      text << " #{docs}"
+    end
+    text.join(' ')
+  end
+
+  private
+
+  def child_shape(rules, options = {})
+    ShapeDocumentor.new(@api, rules, { :prefix => prefix + '    ' }.merge(options))
+  end
+end

package/doc-src/templates/api-versions/plugin.rb

@@ -0,0 +1,230 @@
+require 'json'
+require_relative './model_documentor'
+
+$APIS_DIR = File.expand_path(File.dirname(__FILE__) +
+                             "/../../../vendor/apis/apis")
+$API_FILE_MATCH = /(?:^|\/)([^\/-]+)-(\d+-\d+-\d+)\.full\.json$/
+
+YARD::Tags::Library.define_tag 'Service', :service
+YARD::Tags::Library.define_tag 'Waiter Resource States', :waiter
+YARD::Tags::Library.visible_tags << :waiter
+YARD::Templates::Engine.register_template_path(File.dirname(__FILE__) + '/templates')
+
+class YARD::CodeObjects::ClassObject
+  def title
+    path.gsub(/_(\d{4})(\d{2})(\d{2})/, ' (\1-\2-\3)')
+  end
+
+  def name(prefix = false)
+    return super unless prefix
+    @name.to_s.gsub(/_(\d{4})(\d{2})(\d{2})/, ' (\1-\2-\3)')
+  end
+end
+
+module YARD::Registry
+  class << self
+    @@parsed_apis = false
+
+    def register_aws(object)
+      register_without_aws(object)
+
+      if !@@parsed_apis && object.path == 'AWS'
+        @@parsed_apis = true
+        ApiDocumentor.new(object).run
+      end
+    end
+    alias register_without_aws register
+    alias register register_aws
+  end
+end
+
+class WaiterObject < YARD::CodeObjects::Base
+  attr_accessor :operation
+
+  def parameters; [] end
+  def property_type; 'function' end
+  def sep; '$waiter$' end
+  def title; name.to_s end
+end
+
+class ApiDocumentor
+  def initialize(root = :root)
+    @root = root
+  end
+
+  def run
+    build_map.each do |service, files|
+      files.sort.each.with_index do |file, i|
+        generate_api(file, !(i == files.length - 1))
+      end
+    end
+  end
+
+  def build_map
+    map = {}
+    Dir.entries($APIS_DIR).each do |file|
+      if file =~ $API_FILE_MATCH
+        (map[$1] ||= []).push(File.join($APIS_DIR, file))
+      end
+    end
+    map
+  end
+
+  def generate_api(file, version_suffix = true)
+    _, klass, version = *file.match($API_FILE_MATCH)
+    identifier, klass = *class_info_for(klass.downcase)
+    name = version_suffix ? klass + '_' + version.gsub('-', '') : klass
+
+    log.progress("Parsing AWS.#{klass} (#{version})")
+    svc = YARD::CodeObjects::ClassObject.new(@root, name)
+
+    model = load_model(file)
+    add_class_documentation(svc, klass, model, version)
+    add_methods(svc, klass, model)
+    add_waiters(svc, klass, model)
+
+    svc.docstring.add_tag(YARD::Tags::Tag.new(:service, identifier))
+    svc.docstring.add_tag(YARD::Tags::Tag.new(:version, version))
+    svc.superclass = 'AWS.Service'
+  end
+
+  def add_class_documentation(service, klass, model, api_version)
+    docstring = ModelDocumentor.new(klass, model).lines.join("\n")
+    parser = YARD::Docstring.parser
+    parser.parse(docstring, service)
+    service.docstring = parser.to_docstring
+
+    # constructor
+    ctor = YARDJS::CodeObjects::PropertyObject.new(service, 'constructor')
+    ctor.property_type = :function
+    ctor.parameters = [['options', '{}']]
+    ctor.signature = "constructor(options = {})"
+    ctor.docstring = <<-eof
+Constructs a service object. This object has one method for each
+API operation.
+
+@example Constructing a #{klass} object
+  var #{klass.downcase} = new AWS.#{klass}({apiVersion: '#{api_version}'});
+
+@option options [String] endpoint The endpoint URI to send requests
+  to.  The default endpoint is built from the configured `region`.
+  The endpoint should be a string like `'https://{service}.{region}.amazonaws.com'`.
+@option (see AWS.Config.constructor)
+eof
+
+    # endpoint attribute
+    endpoint = YARDJS::CodeObjects::PropertyObject.new(service, 'endpoint')
+    endpoint.docstring = <<-eof
+@return [AWS.Endpoint] an Endpoint object representing the endpoint URL
+  for service requests.
+eof
+
+  end
+
+  def add_methods(service, klass, model)
+    model['operations'].each_pair do |name, operation|
+      meth = YARDJS::CodeObjects::PropertyObject.new(service, name[0].downcase + name[1..-1])
+      docs = MethodDocumentor.new(name, operation, model, klass).lines.join("\n")
+      meth.property_type = :function
+      meth.parameters = [['params', '{}'], ['callback', nil]]
+      meth.signature = "#{name}(params = {}, [callback])"
+      meth.dynamic = true
+      meth.docstring = docs
+    end
+  end
+
+  def add_waiters(service, klass, model)
+    return unless waiters = model['waiters']
+
+    wait_for = YARDJS::CodeObjects::PropertyObject.new(service, 'waitFor')
+    wait_for.property_type = :function
+    wait_for.parameters = [['state', nil], ['params', '{}'], ['callback', nil]]
+    wait_for.signature = "waitFor(state, params = {}, [callback])"
+    wait_for.dynamic = true
+    wait_for.docstring = <<-eof
+Waits for a given #{service.name} resource. The final callback or
+{AWS.Request~complete 'complete' event} will be fired only when the resource
+is either in its final state or the waiter has timed out and stopped polling
+for the final state.
+
+@param state [String] the resource state to wait for. Available states for this
+  service are listed in "Waiter Resource States" below.
+@param params [map] a list of parameters for the given state. See each waiter
+  resource state for required parameters.
+@callback callback function(err, data)
+  Callback containing error and data information. See the respective resource
+  state for the expected error or data information.
+
+  If the waiter times out its requests, it will return a `ResourceNotReady`
+  error.
+@return [AWS.Request] a handle to the operation request for subsequent event
+  callback registration.
+eof
+
+    waiters.keys.each do |name|
+      next if name =~ /^_/
+      config = load_waiter(waiters, name)
+      operation_name = config['operation'][0,1].downcase + config['operation'][1..-1]
+      name = name[0,1].downcase + name[1..-1]
+      obj = WaiterObject.new(service, name)
+      obj.operation = YARDJS::CodeObjects::PropertyObject.new(service, operation_name)
+      obj.operation.docstring.add_tag YARD::Tags::Tag.new(:waiter, "{#{obj.path}}")
+      obj.docstring = <<-eof
+Waits for the `#{name}` state by periodically calling the underlying
+{#{operation_name}} operation every #{config['interval']} seconds
+(at most #{config['maxAttempts']} times).
+
+@api experimental
+@callback (see #{obj.operation.path})
+@param (see #{obj.operation.path})
+@return (see #{obj.operation.path})
+@see #{operation_name}
+eof
+
+      waiter_ex = ExampleShapeVisitor.new(model, true).example(
+        service.name.to_s.downcase, 'waitFor', model['operations'][config['operation']]['input'])
+      waiter_ex = waiter_ex.sub(/\.waitFor\(/, ".waitFor('#{name}', ")
+      waiter_ex = waiter_ex.sub(/\{\s+\}/, "{\n  // ... input parameters ...\n}")
+      obj.docstring.add_tag YARD::Tags::Tag.new(:example, waiter_ex, nil,
+        "Waiting for the #{name} state")
+      unless wait_for.docstring.tag(:example)
+        wait_for.docstring.add_tag YARD::Tags::Tag.new(:example, waiter_ex, nil,
+          "Waiting for the #{name} state")
+      end
+
+      wait_for.docstring.add_tag YARD::Tags::Tag.new(:waiter, "{#{obj.path}}")
+    end
+  end
+
+  def load_waiter(waiters, name)
+    waiter = waiters[name]
+    if waiter['extends']
+      waiter = waiter.merge(load_waiter(waiters, waiter['extends']))
+    elsif name != '__default__'
+      waiter = waiter.merge(load_waiter(waiters, '__default__'))
+    end
+    waiter
+  end
+
+  def load_model(file)
+    json = JSON.parse(File.read(file))
+
+    waiters_file = file.sub(/\.full\.json$/, '.waiters.json')
+    if File.exist? waiters_file
+      json = json.merge(JSON.parse(File.read(waiters_file)))
+    end
+    json
+  end
+
+  def class_info_for(prefix)
+    @info ||= JSON.parse(File.read(File.join($APIS_DIR, '../metadata.json')))
+    @info.each do |identifier, info|
+      iprefix = info['prefix'] || identifier
+      if prefix == iprefix
+        return [identifier, info['name']]
+      end
+    end
+
+    raise "Unknown class name for #{prefix}"
+  end
+end

package/doc-src/templates/api-versions/templates/default/class/html/setup.rb

@@ -0,0 +1,9 @@
+def init
+  super
+  @waiters = object.children.select {|x| x.type == :waiter }
+  if @waiters.size > 0
+    sections.place(:waiter_summary).before_any(:constant_summary)
+    sections.push(:waiter_details_list, [T('waiter_details')])
+  end
+end
+

package/doc-src/templates/api-versions/templates/default/class/html/waiter_details_list.erb

@@ -0,0 +1,7 @@
+<div id="waiter_details" class="waiter_details_list method_details_list">
+  <h2>Waiter Resource Details</h2>
+
+  <% @waiters.each_with_index do |waiter, i| %>
+    <%= yieldall :object => waiter, :owner => object, :index => i %>
+  <% end %>
+</div>

package/doc-src/templates/api-versions/templates/default/class/html/waiter_summary.erb

@@ -0,0 +1,7 @@
+<h2>Waiter Resource States</h2>
+<p>This service supports a list of resource states that can be polled using
+  the <%= resolve_links "{waitFor}" %> method. The resource states are:</p>
+
+<p class="children">
+  <%= @waiters.map {|waiter| linkify waiter }.join(", ") %>
+</p>

package/doc-src/templates/api-versions/templates/default/docstring/html/experimental.erb

@@ -0,0 +1,4 @@
+<p class="note experimental private">
+  This <%= object.property_type %> is part of an <strong>experimental API</strong>.
+  You can use this <%= object.property_type %>, but it may be removed or be changed in the future.
+</p>

package/doc-src/templates/api-versions/templates/default/docstring/setup.rb

@@ -0,0 +1,9 @@
+def init
+  super
+  sections.place(:experimental).before_any(:private)
+end
+
+def experimental
+  return unless object.has_tag?(:api) && object.tag(:api).text == 'experimental'
+  erb(:experimental)
+end

package/doc-src/templates/api-versions/templates/default/fulldoc/html/css/common.css

@@ -0,0 +1,6 @@
+#full_list li.expander { color: #038; }
+.service_list { list-style: none; padding: 0; margin: 0; font-size: 1.1em; clear: both; }
+.service_list li { border-bottom: 1px solid #ccc; padding-bottom: 5px; margin-bottom: 7px; width: 40%; float: left; margin-right: 7px; }
+#listing .service_list li small { font-size: 0.9em; }
+.clear { clear: both; }
+#capabilities-banner { margin-bottom: 12px; font-weight: bold; padding: 12px; }