Permalink
Browse files

Updated all docs to use YARD doc generator and meta tags.

  • Loading branch information...
1 parent 25639d2 commit ffc499d124a3f9799de9ab98ef469ca3be44a019 @grempe committed Aug 21, 2009
View
@@ -2,5 +2,7 @@
.DS_Store
coverage
rdoc
+doc
+.yardoc
pkg
View
@@ -0,0 +1 @@
+--title amazon-ec2 - ChangeLog LICENSE
View
@@ -1,3 +1,6 @@
+=== 0.5.2 2009-08-20
+ * Converted to YardDoc documentation format. See : http://yard.soen.ca/getting_started
+
=== 0.5.0 2009-08-11
* Major re-factor by Kris Rasmussen (krisr) to add support for the AWS Elastic Load Balancer API. Kudos Kris!
View
@@ -1,4 +1,4 @@
-Copyright (c) 2007-2008 Glenn Rempe
+Copyright (c) 2007-2009 Glenn Rempe
This software is distributed under the Ruby License. A copy of which is
provided below.
View
@@ -305,12 +305,24 @@ So, for example, if you wanted to get the image ID of the third image listed in
EC2 will typically return sets of things (imagesSet, reservationSet, etc.) which we map to ruby Arrays (.imagesSet.item in the example above). If you want to iterate over a response set you will need to iterate over this array. The Arrays will typically contain additional AWS::Response objects that represent each individual item. You'll find that you can use the 'ec2sh' to help you understand the structure more completely if you try issuing commands there as a way to practice seeing what will be returned and making sure you get exactly what you want.
+=== Handling Exceptions
+If for some reason an error occurs when executing a method (e.g. its arguments were
+incorrect, or it simply failed) then an exception will be thrown. The exceptions are
+defined in exceptions.rb as individual classes and should match the exceptions that
+AWS has defined in the API. If the exception raised cannot be identified then a
+more generic exception class will be thrown.
+
+The implication of this is that you need to be prepared to handle any exceptions that
+may be raised by this library in YOUR code with a 'rescue' clause. It is up to you
+to determine how you want to handle these exceptions in your code.
+
== Additional Resources
=== Project Websites
* Project Home : http://github.com/grempe/amazon-ec2/tree/master
+* API Documentation : http://rdoc.info/projects/grempe/amazon-ec2
* Discussion Group : http://groups.google.com/group/amazon-ec2
* Report Bugs / Request Features : http://github.com/grempe/amazon-ec2/issues
* Amazon Web Services : http://aws.amazon.com
@@ -321,7 +333,7 @@ The original code for this library was provided by Amazon Web Services, LLC as s
== Contact
-Comments, patches, Git pull requests and bug reports are welcome. Send an email to mailto:glenn@rempe.us or use the Google Groups forum for this project.
+Comments, patches, Git pull requests and bug reports are welcome. Send an email to mailto:glenn@rempe.us or join the Google Groups forum.
Enjoy!
View
@@ -1,5 +1,6 @@
require 'rubygems'
require 'rake'
+require 'yard'
require 'jeweler'
Jeweler::Tasks.new do |gem|
@@ -47,19 +48,8 @@ end
task :default => :test
-require 'rake/rdoctask'
-Rake::RDocTask.new do |rdoc|
- if File.exist?('VERSION.yml')
- config = YAML.load(File.read('VERSION.yml'))
- version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
- else
- version = ""
- end
-
- rdoc.rdoc_dir = 'rdoc'
- rdoc.title = "amazon-ec2 #{version}"
- rdoc.rdoc_files.include('README*')
- rdoc.rdoc_files.include('lib/**/*.rb')
+YARD::Rake::YardocTask.new do |t|
+ #t.files = ['lib/**/*.rb']
end
begin
@@ -70,15 +60,15 @@ begin
task :release => ["rubyforge:release:gem", "rubyforge:release:docs"]
namespace :release do
- desc "Publish RDoc to RubyForge."
- task :docs => [:rdoc] do
+ desc "Publish YARD docs to RubyForge."
+ task :docs => [:doc] do
config = YAML.load(
File.read(File.expand_path('~/.rubyforge/user-config.yml'))
)
host = "#{config['username']}@rubyforge.org"
remote_dir = "/var/www/gforge-projects/amazon-ec2/"
- local_dir = 'rdoc'
+ local_dir = 'doc'
Rake::SshDirPublisher.new(host, remote_dir, local_dir).upload
end
View
@@ -1,16 +1,47 @@
-# Require any lib files that we have bundled with this Ruby Gem in the lib/AWS directory.
-# Parts of the AWS module and Base class are broken out into separate
-# files for maintainability and are organized by the functional groupings defined
-# in the AWS API developers guide.
-
+#--
+# Amazon Web Services EC2 + ELB API Ruby library
+#
+# Ruby Gem Name:: amazon-ec2
+# Author:: Glenn Rempe (mailto:glenn@rempe.us)
+# Copyright:: Copyright (c) 2007-2009 Glenn Rempe
+# License:: Distributes under the same terms as Ruby
+# Home:: http://github.com/grempe/amazon-ec2/tree/master
+#++
%w[ base64 cgi openssl digest/sha1 net/https rexml/document time ostruct ].each { |f| require f }
+begin
+ require 'xmlsimple' unless defined? XmlSimple
+rescue Exception => e
+ require 'xml-simple' unless defined? XmlSimple
+end
+
+
+# A custom implementation of Hash that allows us to access hash values using dot notation
+#
+# @example Access the hash keys in the standard way or using dot notation
+# foo[:bar] => "baz"
+# foo.bar => "baz"
+class Hash
+ def method_missing(meth, *args, &block)
+ if args.size == 0
+ self[meth.to_s] || self[meth.to_sym]
+ end
+ end
+end
+
+
module AWS
- # Builds the canonical string for signing. This strips out all '&', '?', and '='
- # from the query string to be signed.
- # Note: The parameters in the path passed in must already be sorted in
- # case-insensitive alphabetical order and must not be url encoded.
+
+ # Builds the canonical string for signing requests. This strips out all '&', '?', and '='
+ # from the query string to be signed. The parameters in the path passed in must already
+ # be sorted in case-insensitive alphabetical order and must not be url encoded.
+ #
+ # @param [String] params the params that will be sorted and encoded as a canonical string.
+ # @param [String] host the hostname of the API endpoint.
+ # @param [String] method the HTTP method that will be used to submit the params.
+ # @param [String] base the URI path that this information will be submitted to.
+ # @return [String] the canonical request description string.
def AWS.canonical_string(params, host, method="POST", base="/")
# Sort, and encode parameters into a canonical string.
sorted_params = params.sort {|x,y| x[0] <=> y[0]}
@@ -31,10 +62,15 @@ def AWS.canonical_string(params, host, method="POST", base="/")
end
- # Encodes the given string with the secret_access_key, by taking the
+ # Encodes the given string with the secret_access_key by taking the
# hmac-sha1 sum, and then base64 encoding it. Optionally, it will also
# url encode the result of that to protect the string if it's going to
# be used as a query string parameter.
+ #
+ # @param [String] secret_access_key the user's secret access key for signing.
+ # @param [String] str the string to be hashed and encoded.
+ # @param [Boolean] urlencode whether or not to url encode the result., true or false
+ # @return [String] the signed and encoded string.
def AWS.encode(secret_access_key, str, urlencode=true)
digest = OpenSSL::Digest::Digest.new('sha1')
b64_hmac =
@@ -48,10 +84,21 @@ def AWS.encode(secret_access_key, str, urlencode=true)
end
end
+ # This class provides all the methods for using the EC2 or ELB service
+ # including the handling of header signing and other security concerns.
+ # This class uses the Net::HTTP library to interface with the AWS Query API
+ # interface. You should not instantiate this directly, instead
+ # you should setup an instance of 'AWS::EC2::Base' or 'AWS::ELB::Base'.
class Base
attr_reader :use_ssl, :server, :proxy_server, :port
+ # @option options [String] :access_key_id ("") The user's AWS Access Key ID
+ # @option options [String] :secret_access_key ("") The user's AWS Secret Access Key
+ # @option options [Boolean] :use_ssl (true) Connect using SSL?
+ # @option options [String] :server ("ec2.amazonaws.com") The server API endpoint host
+ # @option options [String] :proxy_server (nil) An HTTP proxy server FQDN
+ # @return [Object] the object.
def initialize( options = {} )
options = { :access_key_id => "",
@@ -242,4 +289,5 @@ def aws_error?(response)
end
end
-Dir[File.join(File.dirname(__FILE__), 'AWS/*.rb')].sort.each { |lib| require lib }
+Dir[File.join(File.dirname(__FILE__), 'AWS/**/*.rb')].sort.each { |lib| require lib }
+
View
@@ -1,58 +1,23 @@
-#--
-# Amazon Web Services EC2 Query API Ruby library
-#
-# Ruby Gem Name:: amazon-ec2
-# Author:: Glenn Rempe (mailto:glenn@rempe.us)
-# Copyright:: Copyright (c) 2007-2008 Glenn Rempe
-# License:: Distributes under the same terms as Ruby
-# Home:: http://github.com/grempe/amazon-ec2/tree/master
-#++
-
-# Require any lib files that we have bundled with this Ruby Gem in the lib/EC2 directory.
-# Parts of the EC2 module and Base class are broken out into separate
-# files for maintainability and are organized by the functional groupings defined
-# in the EC2 API developers guide.
-Dir[File.join(File.dirname(__FILE__), 'EC2/**/*.rb')].sort.each { |lib| require lib }
-
module AWS
module EC2
# Which host FQDN will we connect to for all API calls to AWS?
- # If EC2_URL is defined in the users ENV we can use that. It is
- # expected that this var is set with something like:
- # export EC2_URL='https://ec2.amazonaws.com'
+ # If EC2_URL is defined in the users ENV we can override the default with that.
#
+ # @example
+ # export EC2_URL='https://ec2.amazonaws.com'
if ENV['EC2_URL']
EC2_URL = ENV['EC2_URL']
VALID_HOSTS = ['https://ec2.amazonaws.com', 'https://us-east-1.ec2.amazonaws.com', 'https://eu-west-1.ec2.amazonaws.com']
raise ArgumentError, "Invalid EC2_URL environment variable : #{EC2_URL}" unless VALID_HOSTS.include?(EC2_URL)
DEFAULT_HOST = URI.parse(EC2_URL).host
else
- # default US host
+ # Default US API endpoint
DEFAULT_HOST = 'ec2.amazonaws.com'
end
- # This is the version of the API as defined by Amazon Web Services
API_VERSION = '2008-12-01'
- #Introduction:
- #
- # The library exposes one main interface class, 'AWS::EC2::Base'.
- # This class provides all the methods for using the EC2 service
- # including the handling of header signing and other security issues .
- # This class uses Net::HTTP to interface with the EC2 Query API interface.
- #
- #Required Arguments:
- #
- # :access_key_id => String (default : "")
- # :secret_access_key => String (default : "")
- #
- #Optional Arguments:
- #
- # :use_ssl => Boolean (default : true)
- # :server => String (default : 'ec2.amazonaws.com')
- # :proxy_server => String (default : nil)
- #
class Base < AWS::Base
def api_version
API_VERSION
@@ -64,4 +29,5 @@ def default_host
end
end
-end
+end
+
@@ -1,43 +1,21 @@
-#--
-# Amazon Web Services EC2 Query API Ruby library
-#
-# Ruby Gem Name:: amazon-ec2
-# Author:: Glenn Rempe (mailto:glenn@rempe.us)
-# Copyright:: Copyright (c) 2007-2008 Glenn Rempe
-# License:: Distributes under the same terms as Ruby
-# Home:: http://github.com/grempe/amazon-ec2/tree/master
-#++
-
module AWS
module EC2
-
class Base < AWS::Base
- #Amazon Developer Guide Docs:
- #
# The DescribeAvailabilityZones operation describes availability zones that are currently
# available to the account and their states.
#
# An optional list of zone names can be passed.
#
- #Required Arguments:
- #
- # none
+ # @option options [optional, String] :zone_name ([]) an Array of zone names
#
- #Optional Arguments:
- #
- # :zone_name => Array (default : [])
- #
-
def describe_availability_zones( options = {} )
-
options = { :zone_name => [] }.merge(options)
-
params = pathlist("ZoneName", options[:zone_name] )
-
return response_generator(:action => "DescribeAvailabilityZones", :params => params)
-
end
+
end
end
-end
+end
+
@@ -1,46 +1,23 @@
-#--
-# Amazon Web Services EC2 Query API Ruby library
-#
-# Ruby Gem Name:: amazon-ec2
-# Author:: Glenn Rempe (mailto:glenn@rempe.us)
-# Copyright:: Copyright (c) 2007-2008 Glenn Rempe
-# License:: Distributes under the same terms as Ruby
-# Home:: http://github.com/grempe/amazon-ec2/tree/master
-#++
-
module AWS
module EC2
-
class Base < AWS::Base
- #Amazon Developer Guide Docs:
- #
# The GetConsoleOutput operation retrieves console output that has been posted for the specified instance.
#
# Instance console output is buffered and posted shortly after instance boot, reboot and once the instance
# is terminated. Only the most recent 64 KB of posted output is available. Console output is available for
# at least 1 hour after the most recent post.
#
- #Required Arguments:
- #
- # :instance_id => String (default : "")
+ # @option options [String] :instance_id ("") an Instance ID
#
- #Optional Arguments:
- #
- # none
- #
- def get_console_output( options ={} )
-
+ def get_console_output( options = {} )
options = {:instance_id => ""}.merge(options)
-
raise ArgumentError, "No instance ID provided" if options[:instance_id].nil? || options[:instance_id].empty?
-
params = { "InstanceId" => options[:instance_id] }
-
return response_generator(:action => "GetConsoleOutput", :params => params)
-
end
- end
+ end
end
-end
+end
+
Oops, something went wrong.

0 comments on commit ffc499d

Please sign in to comment.