Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Add documentation for waiter resources

  • Loading branch information...
commit c38ca9f2bb641f1a3ea996cc0d9115a2b2445dd9 1 parent 3db4405
@lsegal lsegal authored
View
1  doc-src/templates/api-versions/model_documentor.rb
@@ -78,7 +78,6 @@ def find_example_operation(api)
list = api['operations'].keys if list.size == 0
list.first
end
-
end
class MethodDocumentor
View
52 doc-src/templates/api-versions/plugin.rb
@@ -2,6 +2,8 @@
require_relative './model_documentor'
YARD::Tags::Library.define_tag 'Service', :service
+YARD::Tags::Library.define_tag 'Waiter Resources', :waiter
+YARD::Tags::Library.visible_tags << :waiter
YARD::Templates::Engine.register_template_path(File.dirname(__FILE__) + '/templates')
class YARD::CodeObjects::ClassObject
@@ -15,6 +17,14 @@ def name(prefix = false)
end
end
+class WaiterObject < YARD::CodeObjects::Base
+ attr_accessor :operation
+
+ def parameters; [] end
+ def sep; '$waiter$' end
+ def title; name.to_s end
+end
+
class DefineServiceHandler < YARDJS::Handlers::Base
handles AssignmentExpression
@@ -42,6 +52,7 @@ def generate_api(klass, right, identifier, version, version_suffix = true)
model = load_model(klass.downcase, version)
add_class_documentation(svc, klass, model)
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))
@@ -65,12 +76,51 @@ def add_methods(service, klass, model)
docs = MethodDocumentor.new(operation, model, klass).lines.join("\n")
meth.property_type = :function
meth.parameters = [['params', '{}'], ['callback', nil]]
- meth.signature = "#{name}(params = {}, callback)"
+ 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 = "Waits for a given #{service.name} resource."
+
+ waiters.keys.each do |name|
+ next if name =~ /^_/
+ config = load_waiter(waiters, name)
+ operation_name = config['operation'][0,1].downcase + config['operation'][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, calling the underlying {#{operation_name}} operation.
+
+@callback (see #{obj.operation.path})
+@param (see #{obj.operation.path})
+@return (see #{obj.operation.path})
+eof
+
+ 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(klass, api_version)
# get real endpoint prefix for json models
config = File.read(File.dirname(__FILE__) + "/../../../apis/#{klass}-#{api_version}.json")
View
9 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
+
View
7 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>
View
4 doc-src/templates/api-versions/templates/default/class/html/waiter_summary.erb
@@ -0,0 +1,4 @@
+<h2>Waiter Resources</h2>
+<p class="children">
+ <%= @waiters.map {|waiter| linkify waiter }.join(", ") %>
+</p>
View
3  doc-src/templates/api-versions/templates/default/tags/setup.rb
@@ -0,0 +1,3 @@
+def param
+ tag(:param) if [:property, :event, :waiter].include?(object.type)
+end
View
3  doc-src/templates/api-versions/templates/default/waiter_details/html/method_signature.erb
@@ -0,0 +1,3 @@
+<h3 class="signature <%= 'first' if @index == 0 %>" id="<%= anchor_for(object) %>">
+ <small>(<%= linkify P('AWS.Request') %>)</small> <%= owner.tag(:service).text %>.waitFor('<strong><%= object.name %></strong>', params = {}, [callback])
+</h3>
View
5 doc-src/templates/api-versions/templates/default/waiter_details/html/setup.rb
@@ -0,0 +1,5 @@
+include T('default/method_details/html')
+
+def init
+ sections :header, [:method_signature, T('docstring')]
+end
Please sign in to comment.
Something went wrong with that request. Please try again.