client_constructor_docstring()
click to toggle source
def client_constructor_docstring
"Constructs an API client.
#{client_constructor_options}
@return [#{@client_class.name}] Returns an API client.
".strip
end
client_constructor_options()
click to toggle source
def client_constructor_options
options = {}
@client_class.plugins.each do |plugin|
if p = YARD::Registry[plugin.name]
p.tags.each do |tag|
if tag.tag_name == 'seahorse_client_option'
option_name = tag.text.match(/.+(:\w+)/)[1]
option_text = "@option options " + tag.text.split("\n").join("\n ")
options[option_name] = option_text +
" See {#{plugin.name}} for more details."
end
end
end
end
options.sort_by { |k,v| k }.map(&:last).join("\n")
end
client_docstring()
click to toggle source
def client_docstring
path = "doc-src/services/#{@svc_name}/client.md"
path = 'doc-src/services/default/client.md' unless File.exists?(path)
render(path)
end
document_client()
click to toggle source
def document_client
yard_class = YARD::CodeObjects::ClassObject.new(@namespace, 'Client')
yard_class.superclass = YARD::Registry['Seahorse::Client::Base']
yard_class.docstring = client_docstring
document_client_constructor(yard_class)
document_client_operations(yard_class)
document_client_waiters(yard_class)
end
document_client_constructor(namespace)
click to toggle source
def document_client_constructor(namespace)
constructor = YARD::CodeObjects::MethodObject.new(namespace, :initialize)
constructor.group = 'Constructor'
constructor.scope = :instance
constructor.parameters << ['options', '{}']
constructor.docstring = client_constructor_docstring
end
document_client_operation(namespace, method_name, operation)
click to toggle source
def document_client_operation(namespace, method_name, operation)
m = YARD::CodeObjects::MethodObject.new(namespace, method_name)
m.group = 'Service Operations'
m.scope = :instance
m.parameters << ['params', '{}']
m.docstring = operation_docstring(method_name, operation)
end
document_client_operations(namespace)
click to toggle source
def document_client_operations(namespace)
@api.operations.each do |method_name, operation|
document_client_operation(namespace, method_name, operation)
end
end
document_client_waiters(yard_class)
click to toggle source
def document_client_waiters(yard_class)
m = YARD::CodeObjects::MethodObject.new(yard_class, :wait_until)
m.scope = :instance
m.parameters << ['waiter_name', nil]
m.parameters << ['params', '{}']
m.docstring = YARD::Registry['Aws::ClientWaiters#wait_until'].docstring
waiters = @client_class.waiters.waiter_names.sort.inject('') do |w,name|
waiter = @client_class.waiters.waiter(name)
operation = waiter.poller.operation_name
w << "<tr><td><tt>:#{name}</tt></td><td>{##{operation}}</td><td>#{waiter.delay}</td><td>#{waiter.max_attempts}</td></tr>"
end
docstring = <<-DOCSTRING
Returns the list of supported waiters. The following table lists the supported
waiters and the client method they call:
<table>
<thead>
<tr><th>Waiter Name</th><th>Client Method</th><th>Delay</th><th>Max Attempts</th></tr>
</thead>
<tbody>
#{waiters}
</tbody>
</table>
@return [Array<Symbol>] the list of supported waiters.
DOCSTRING
m = YARD::CodeObjects::MethodObject.new(yard_class, :waiter_names)
m.scope = :instance
m.docstring = docstring
end
document_errors()
click to toggle source
def document_errors
yard_mod = YARD::CodeObjects::ModuleObject.new(@namespace, 'Errors')
yard_mod.docstring = errors_docstring
base_error = YARD::CodeObjects::ClassObject.new(yard_mod, 'ServiceError')
base_error.docstring = "Base class for all Aws::#{@svc_name} errors."
base_error.superclass = YARD::Registry['Aws::Errors::ServiceError']
@error_names.each do |error_name|
error_klass = YARD::CodeObjects::ClassObject.new(yard_mod, error_name)
error_klass.superclass = base_error
end
end
document_service()
click to toggle source
def document_service
yard_mod = YARD::CodeObjects::ModuleObject.new(@namespace, @svc_name)
yard_mod.docstring = service_docstring
yard_mod.docstring.add_tag(YARD::Tags::Tag.new(:service, @svc_name))
@namespace = yard_mod
end
errors_docstring()
click to toggle source
def errors_docstring
path = "doc-src/services/#{@svc_name}/errors.md"
path = 'doc-src/services/default/errors.md' unless File.exists?(path)
template = read(path)
svc_name = @svc_name
api = @api
full_name = @full_name
known_errors = @error_names
ERB.new(template).result(binding)
end
operation_docstring(method_name, operation)
click to toggle source
def operation_docstring(method_name, operation)
documentor = OperationDocumenter.new(
svc_var_name: @svc_name.downcase,
method_name: method_name,
operation: operation)
tabs = Tabulator.new.tap do |t|
t.tab(method_name, 'Formatting Example') do
"<pre><code>#{documentor.example}</code></pre>"
end
t.tab(method_name, 'Request Parameters') do
documentor.input
end
t.tab(method_name, 'Response Structure') do
documentor.output
end
end
errors = (operation.errors || []).map { |shape| shape.name }
errors = errors.map { |e| "@raise [Errors::#{e}]" }.join("\n")
docstring = "<p>Calls the #{operation.name} operation.<p>
#{documentor.api_ref(operation)}
#{tabs}
@param [Hash] params ({})
@return [PageableResponse]
#{errors}
".strip
end
read(path)
click to toggle source
def read(path)
File.open(path, 'r', encoding: 'UTF-8') { |f| f.read }
end
render(path)
click to toggle source
def render(path)
svc_name = @svc_name
api = @api
full_name = @full_name
ERB.new(File.read(path)).result(binding)
end
service_docstring()
click to toggle source
def service_docstring
path = "doc-src/services/#{@svc_name}/service.md"
path = 'doc-src/services/default/service.md' unless File.exists?(path)
template = read(path)
svc_name = @svc_name
api = @api
full_name = @full_name
ERB.new(template).result(binding)
end