bisques 1.0.1 → 1.0.2

data/CHANGELOG

@@ -0,0 +1,7 @@
+=== v1.0.1
+
+Corrected homepage link
+
+=== v1.0.0 
+
+First version

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Jeremy Wells
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -45,7 +45,7 @@ fibonacci sequence, with the consumer script doing the actual calculation.
 
 == LICENSE
 
-Copyright (c) 2012 Jeremy Wells
+Copyright (c) 2013 Jeremy Wells
 
 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation

data/lib/bisques.rb

@@ -1,4 +1,4 @@
-# See README.rdoc
+# See {file:README README}
 module Bisques
   class Error < StandardError; end
   class MessageHasWrongMd5Error < Error

data/lib/bisques/aws_connection.rb

@@ -17,9 +17,20 @@ module Bisques
   end
 
   # This module is for making API classes more convenient. The including class
-  # must pass the correct params via super from it's #initialize call. Two
-  # useful methods are added to the including class, #request and #action.
+  # must pass the correct params via super from it's {#initialize} call. Two
+  # useful methods are added to the including class, {#request} and {#action}.
+  #
+  # @example
+  #   class Sqs
+  #     include AwsConnection
+  #
+  #     def initialize(region)
+  #       super(region, 'sqs')
+  #     end
+  #   end
+  # 
   module AwsConnection
+    # @!visibility private
     def self.included(mod) # :nodoc:
       mod.class_eval do
         attr_accessor :credentials, :region, :service
@@ -28,8 +39,11 @@ module Bisques
 
     # Give the region, service and optionally the AwsCredentials.
     #
-    # === Example:
+    # @param [String] region the AWS region (ex. us-east-1)
+    # @param [String] service the AWS service (ex. sqs)
+    # @param [AwsCredentials] credentials
     #
+    # @example
     #   class Sqs
     #     include AwsConnection
     #
@@ -42,19 +56,19 @@ module Bisques
       @region, @service, @credentials = region, service, credentials
     end
 
-    def connection # :nodoc:
-      @connection ||= HTTPClient.new.tap do |http|
-        http.ssl_config.verify_mode = OpenSSL::SSL::VERIFY_NONE
-        http.receive_timeout = 30
-      end
-    end
-
     # Perform an HTTP query to the given path using the given method (GET,
     # POST, PUT, DELETE). A hash of query params can be specified. A POST or
     # PUT body cna be specified as either a string or a hash of form params. A
     # hash of HTTP headers can be specified.
+    #
+    # @param [String] method HTTP method, should be GET, POST, PUT or DELETE
+    # @param [String] path
+    # @param [Hash] query HTTP query params to send. Specify these as a hash, do not append them to the path.
+    # @param [Hash,#to_s] body HTTP request body. This can be form data as a hash or a String. Only applies to POST and PUT HTTP methods.
+    # @param [Hash] headers additional HTTP headers to send.
+    # @return [AwsRequest]
     def request(method, path, query = {}, body = nil, headers = {})
-      AwsRequest.new(connection).tap do |aws_request|
+      AwsRequest.new(aws_http_connection).tap do |aws_request|
         aws_request.credentials = credentials
         aws_request.path = path
         aws_request.region = region
@@ -68,13 +82,17 @@ module Bisques
     end
 
     # Call an AWS API with the given name at the given path. An optional hash
-    # of options can be passed as arguments for the API call. Returns an
-    # AwsResponse. If the response is not successful then an AwsActionError is
-    # raised and the error information is extracted into the exception
-    # instance.
+    # of options can be passed as arguments for the API call. 
+    # 
+    # @note The API call will be automatically retried *once* if the returned status code is
+    #   in the 500 range.
     #
-    # The API call will be automatically retried if the returned status code is
-    # in the 500 range.
+    # @param [String] action_name
+    # @param [String] path
+    # @param [Hash] options
+    # @return [AwsResponse]
+    # @raise [AwsActionError] if the response is not successful. AWS error
+    #   information can be extracted from the exception.
     def action(action_name, path = "/", options = {})
       retries = 0
 
@@ -96,5 +114,13 @@ module Bisques
         end
       end
     end
+
+    private
+    def aws_http_connection
+      @aws_http_connection ||= HTTPClient.new.tap do |http|
+        http.ssl_config.verify_mode = OpenSSL::SSL::VERIFY_NONE
+        http.receive_timeout = 30
+      end
+    end
   end
 end

data/lib/bisques/aws_credentials.rb

@@ -2,18 +2,23 @@ module Bisques
   # Represents an AWS key/secret combination. Provides a convenient class
   # method for setting defaults that can be used by all objects later on.
   #
-  # Example:
+  # @example
   #
   #   AwsCredentials.default('aws_key', 'aws_secret')
   #
   class AwsCredentials
+    # @return [String]
     attr_reader :aws_key, :aws_secret
 
+    # @param [String] aws_key
+    # @param [String] aws_secret
     def initialize(aws_key, aws_secret)
       @aws_key, @aws_secret = aws_key, aws_secret
     end
 
     class << self
+      # (see #initialize)
+      # Set or retrieve the default credentials
       def default(*args)
         if args.size == 2
           @default = AwsCredentials.new(*args)

data/lib/bisques/aws_request.rb

@@ -4,10 +4,10 @@ require 'bisques/aws_response'
 module Bisques
   # A request to an AWS API call. This class must be initiated with a client
   # instance of HTTPClient. A number of mandatory attributes must be set before
-  # calling make_request to return the response. #make_request returns an
-  # AwsResponse object.
+  # calling {#make_request} to return the response. {#make_request} returns an
+  # {AwsResponse} object.
   #
-  # === Example
+  # @example
   #
   #   request = AwsRequest.new(httpclient)
   #   request.method = "GET" or "POST"
@@ -18,47 +18,55 @@ module Bisques
   #   request.region = "AWS region (ex. us-east-1)"
   #   request.service = "AWS service (ex. sqs)"
   #   request.credentials = AwsCredentials.new("aws_key", "aws_secret")
-  #   response = request.make_request => Returns AwsResponse
+  #   response = request.make_request
   #
   class AwsRequest
-    # The HTTP method to use. Should be GET or POST.
+    # @return [String] The HTTP method to use. Should be GET or POST.
     attr_accessor :method
-    # A hash describing the query params to send.
+    # @return [Hash] A hash describing the query params to send.
     attr_accessor :query
-    # A hash or string describing the form params or HTTP body. Only used when
-    # the method is POST or PUT.
+    # @return [Hash,String] A hash or string describing the form params or HTTP body. Only used when
+    #   the method is POST or PUT.
     attr_accessor :body
-    # A hash of additional HTTP headers to send with the request.
+    # @return [Hash] A hash of additional HTTP headers to send with the request.
     attr_accessor :headers
-    # The path to the API call. This shouldn't be the full URL as the host part
-    # is built from the region and service.
+    # @return [String] The path to the API call. This shouldn't be the full URL as the host part
+    #   is built from the region and service.
     attr_accessor :path
-    # The AWS region. Ex: us-east-1
+    # @return [String] The AWS region. Ex: us-east-1
     attr_accessor :region
-    # The AWS service. Ex: sqs
+    # @return [String] The AWS service. Ex: sqs
     attr_accessor :service
-    # The AWS credentials. Should respond to aws_key and aws_secret. Use
-    # AwsCredentials.
+    # @return [AwsCredentials] The AWS credentials. Should respond to aws_key and aws_secret.
     attr_accessor :credentials
 
-    # An AwsResponse object describing the response. Returns nil until
-    # #make_request has been called.
+    # @return [AwsResponse] An AwsResponse object describing the response. Returns nil until
+    #   {#make_request} has been called.
     attr_reader :response
+    # @return [AwsRequestAuthorization]
+    # @!visibility private
     attr_reader :authorization # :nodoc:
 
     # AWS has some particular rules about how it likes it's form params encoded.
+    #
+    # @param [String] value
+    # @return [String] encoded value
     def self.aws_encode(value)
       value.to_s.gsub(/([^a-zA-Z0-9._~-]+)/n) do
         '%' + $1.unpack('H2' * $1.size).join('%').upcase
       end
     end
 
-    # Create a new AwsRequest using the given HTTPClient object.
+    # Create a new {AwsRequest} using the given HTTPClient object.
+    #
+    # @param [HTTPClient] httpclient
     def initialize(httpclient)
       @httpclient = httpclient
     end
 
     # The full URL to the API endpoint the request will call.
+    #
+    # @return [String]
     def url
       File.join("https://#{service}.#{region}.amazonaws.com", path)
     end

data/lib/bisques/aws_response.rb

@@ -2,14 +2,14 @@ require 'nokogiri'
 
 module Bisques
   # Created by an AwsRequest to represent the returned details. The original
-  # request is stored in #request. The raw content is available in #content.
-  # AWS returns XML, and a Nokogiri::XML instance is available in #doc.
+  # request is stored in {#request}. The raw content is available in {#content}.
+  # AWS returns XML, and a Nokogiri::XML instance is available in {#doc}.
   class AwsResponse
-    # The original AwsRequest that created this response.
+    # @return [AwsRequest] The original AwsRequest that created this response.
     attr_reader :request
-    # The raw response string from AWS
+    # @return [String] The raw response string from AWS
     attr_reader :content
-    # The HTTP response. This can be used to get any headers or status codes.
+    # @return [#body,#status,#header] The HTTP response. This can be used to get any headers or status codes.
     attr_reader :http_response
 
     def initialize(request, http_response) # :nodoc:
@@ -18,17 +18,19 @@ module Bisques
       @content = @http_response.body
     end
 
-    # A Nokogiri::XML document parsed from the #content.
+    # A Nokogiri::XML document parsed from the {#content}.
+    #
+    # @return [Nokogiri::XML] XML document
     def doc
       @doc ||= Nokogiri::XML(content).tap{|x|x.remove_namespaces!}
     end
 
-    # Returns true if the request was successful.
+    # @return [Boolean] Returns true if the request was successful.
     def success?
       @http_response.ok?
     end
 
-    # The request ID from AWS.
+    # @return [String] The request ID from AWS.
     def request_id
       @http_response.header['x-amzn-RequestId']
     end

data/lib/bisques/client.rb

@@ -5,25 +5,29 @@ require 'bisques/queue_listener'
 require 'digest/md5'
 
 module Bisques
+  class QueueDeletedRecentlyError << Bisques::Error
+  end
+
   # Bisques is a client for Amazon SQS. All of the API calls made to SQS are
   # called via methods on this class.
   #
-  # === Example
+  # @example
   #
   #   client = Bisques::Client.new('us-east-1', 'my_queues_', AwsCredentials.new(aws_key, aws_secret))
   #   client.list_queues
   #
   class Client
-    # The queue prefix when interacting with SQS. The client will only be able
+    # @return [String] The queue prefix when interacting with SQS. The client will only be able
     # to see queues whose name has this prefix.
     attr_accessor :queue_prefix
 
     include AwsConnection
 
-    # Initialize a client object. The AWS region must be specified. For
-    # example, 'us-east-1'. An optional queue prefix can be provided to
-    # restrict the queues this client can see and interact with. AWS
-    # credentials must be provided, or defaults set in AwsCredentials.
+    # Initialize a client object.
+    #
+    # @param [String] region the AWS region.
+    # @param [String] queue_prefix an optional prefix for all queue names for this instance.
+    # @param [AwsCredentials] credentials an instance of AwsCredentials. Uses AwsCredentials::default if not provided.
     def initialize(region, queue_prefix = nil, credentials = AwsCredentials.default)
       super(region, "sqs", credentials)
       @queue_prefix = queue_prefix
@@ -31,11 +35,20 @@ module Bisques
 
     # Returns a Queue object representing an SQS queue, creating it if it does
     # not already exist.
+    #
+    # @param [String] name
+    # @return [Queue]
+    # @raise [AwsActionError]
     def get_or_create_queue(name)
       get_queue(name) || create_queue(name, {})
     end
 
     # Creates a new SQS queue and returns a Queue object.
+    #
+    # @param [String] name
+    # @param [Hash] attributes
+    # @return [Queue]
+    # @raise [AwsActionError]
     def create_queue(name, attributes = {})
       response = action("CreateQueue", {"QueueName" => Queue.sanitize_name("#{queue_prefix}#{name}")}.merge(attributes))
 
@@ -44,14 +57,28 @@ module Bisques
       else
         raise "Could not create queue #{name}"
       end
+
+    rescue AwsActionError => error
+      if error.code == "AWS.SimpleQueueService.QueueDeletedRecently"
+        raise QueueDeletedRecentlyError, error.message
+      else
+        raise error
+      end
     end
 
     # Deletes an SQS queue at a given path.
+    # @param [String] queue_url
+    # @return [AwsResponse]
+    # @raise [AwsActionError]
     def delete_queue(queue_url)
       response = action("DeleteQueue", queue_url)
     end
 
-    # Get an SQS queue by name. Returns a Queue object if the queue is found, otherwise nil.
+    # Get an SQS queue by name. 
+    # @param [String] name
+    # @param [Hash] options
+    # @return [Queue,nil] Returns a Queue object if the queue is found, otherwise nil.
+    # @raise [AwsActionError]
     def get_queue(name, options = {})
       response = action("GetQueueUrl", {"QueueName" => Queue.sanitize_name("#{queue_prefix}#{name}")}.merge(options))
       
@@ -67,9 +94,12 @@ module Bisques
     # optional prefix can be supplied to restrict the queues found. This prefix
     # is additional to the client prefix.
     #
-    # Example:
+    # @param [String] prefix option prefix to restrict the queues found.
+    # @return [Array<Queue>] queue objects found.
+    # @raise [AwsActionError]
+    #
+    # @example Delete all the queues
     #
-    #   # Delete all the queues
     #   client.list_queues.each do |queue|
     #     queue.delete
     #   end
@@ -84,7 +114,10 @@ module Bisques
     # Get the attributes for a queue. Takes an array of attribute names.
     # Defaults to ["All"] which returns all the available attributes.
     #
-    # This returns an AwsResponse object.
+    # @param [String] queue_url
+    # @param [Array<String>] attributes
+    # @return [AwsResponse]
+    # @raise [AwsActionError]
     def get_queue_attributes(queue_url, attributes = ["All"])
       attributes = attributes.map(&:to_s)
 
@@ -99,7 +132,14 @@ module Bisques
     # should be a string. An optional delay seconds argument can be added if
     # the message should not become visible immediately.
     #
-    # Example:
+    # @param [String] queue_url
+    # @param [String] message_body
+    # @param [Fixnum] delay_seconds
+    # @return nil
+    # @raise [MessageHasWrongMd5Error]
+    # @raise [AwsActionError]
+    #
+    # @example
     #
     #   client.send_message(queue.path, "test message")
     #
@@ -127,11 +167,20 @@ module Bisques
 
     # Delete a message from a queue. The message is deleted by the handle given
     # when the message is retrieved.
+    #
+    # @param [String] queue_url
+    # @param [String] receipt_handle
+    # @return [AwsResponse]
+    # @raise [AwsActionError]
     def delete_message(queue_url, receipt_handle)
-      response = action("DeleteMessage", queue_url, {"ReceiptHandle" => receipt_handle})
+      action("DeleteMessage", queue_url, {"ReceiptHandle" => receipt_handle})
     end
 
     # Receive a message from a queue. Takes the queue url and an optional hash.
+    # @param [String] queue_url
+    # @param [Hash] options
+    # @return [AwsResponse]
+    # @raise [AwsActionError]
     def receive_message(queue_url, options = {})
       # validate_options(options, %w(AttributeName MaxNumberOfMessages VisibilityTimeout WaitTimeSeconds))
       action("ReceiveMessage", queue_url, options)
@@ -141,6 +190,12 @@ module Bisques
     # have retrieved a message and now want to keep it hidden for longer before
     # deleting it, or if you have a job and decide you cannot action it and
     # want to return it to the queue sooner.
+    #
+    # @param [String] queue_url
+    # @param [String] receipt_handle
+    # @param [Fixnum] visibility_timeout
+    # @return [AwsResponse]
+    # @raise [AwsActionError]
     def change_message_visibility(queue_url, receipt_handle, visibility_timeout)
       action("ChangeMessageVisibility", queue_url, {"ReceiptHandle" => receipt_handle, "VisibilityTimeout" => visibility_timeout})
     end

data/lib/bisques/message.rb

@@ -3,17 +3,23 @@ require 'json'
 module Bisques
   # A message received from an SQS queue.
   class Message
-    # The queue this message originated from.
+    # @return [Queue] The queue this message originated from.
     attr_reader :queue
-    # The AWS Id of the message.
+    # @return [String] The AWS Id of the message.
     attr_reader :id
-    # A unique handle used to manipulate the message.
+    # @return [String] A unique handle used to manipulate the message.
     attr_reader :handle
-    # The raw text body of the message.
+    # @return [String] The raw text body of the message.
     attr_reader :body
-    # Hash of SQS attributes.
+    # @return [Hash] Hash of SQS attributes.
     attr_reader :attributes
 
+    # @api
+    # @param [Queue] queue
+    # @param [String] id
+    # @param [String] handle
+    # @param [String] body
+    # @param [Hash] attributes
     def initialize(queue, id, handle, body, attributes = {}) #:nodoc:
       @queue, @id, @handle, @body, @attributes = queue, id, handle, body, attributes
     end
@@ -21,15 +27,17 @@ module Bisques
     # The deserialized object in the message. This method is used to retrieve
     # the contents that Queue#post_message placed there.
     #
-    # Example:
+    # @example
     #
     #   queue.post_message([1,2,3])
-    #   queue.retrieve.object => [1,2,3]
+    #   queue.retrieve.object == [1,2,3]
     #
     def object
       @object ||= JSON.parse(body)
     end
 
+    # @return (see Queue#delete_message)
+    # @raise (see Queue#delete_message)
     # Delete the message from the queue. This should be called after the
     # message has been received and processed. If not then after a timeout the
     # message will get added back to the queue.
@@ -37,6 +45,8 @@ module Bisques
       queue.delete_message(handle)
     end
 
+    # @return (see Queue#return_message)
+    # @raise (see Queue#return_message)
     # Return the message to the queue immediately. If a client has taken a
     # message and cannot process it for any reason it can put the message back
     # faster than the default timeout by calling this method.

data/lib/bisques/queue.rb

@@ -11,9 +11,10 @@ module Bisques
     end
     class QueueNotFound < QueueError; end
 
-
+    # @!visibility private
     attr_reader :client # :nodoc:
 
+    # @!visibility private
     def self.sanitize_name(name)
       name = name.gsub(/[^_\w\d]/, "")
 
@@ -27,18 +28,21 @@ module Bisques
       name
     end
 
-    # Queues are created by the Client passing the client itself and the url
+    # Queues are created by the {Client} passing the client itself and the url
     # for the queue.
+    #
+    # @param [Client] client
+    # @param [String] url
     def initialize(client, url)
       @client, @url = client, url
     end
 
-    # The name of the queue derived from the URL.
+    # @return [String] The name of the queue derived from the URL.
     def name
       @url.split("/").last
     end
 
-    # The path part of the queue URL
+    # @return [String] The path part of the queue URL
     def path
       Addressable::URI.parse(@url).path
     end
@@ -50,7 +54,7 @@ module Bisques
     def ==(queue)
       hash == queue.hash
     end
-    def hash # :nodoc:
+    def hash
       @url.hash
     end
 
@@ -63,13 +67,16 @@ module Bisques
     # If more than one, or all, attributes are requested then a hash of
     # attribute names and values is returned.
     #
-    # ==== Example with one attribute:
+    # @param [String] attributes
+    # @return [Object,Hash]
     #
-    #   queue.attributes(:ApproximateNumberOfMessages) => 10
+    # @example with one attribute
     #
-    # ==== Example with multiple attributes:
+    #   queue.attributes(:ApproximateNumberOfMessages) == 10
     #
-    #   queue.attributes(:ApproximateNumberOfMessages, :ApproximateNumberOfMessagesDelayed) => {:ApproximateNumberOfMessages => 10, :ApproximateNumberOfMessagesDelayed => 5}
+    # @example with multiple attributes
+    #
+    #   queue.attributes(:ApproximateNumberOfMessages, :ApproximateNumberOfMessagesDelayed) == {:ApproximateNumberOfMessages => 10, :ApproximateNumberOfMessagesDelayed => 5}
     #
     def attributes(*attributes)
       return nil if attributes.blank?
@@ -92,18 +99,28 @@ module Bisques
     end
 
     # Delete the queue
+    # @return [AwsResponse]
+    # @raise [AwsActionError]
     def delete
       client.delete_queue(url)
     end
 
     # Post a message to the queue. The message must be serializable (i.e.
     # strings, numbers, arrays, hashes).
+    #
+    # @param [String,Fixnum,Array,Hash] object
+    # @raise [MessageHasWrongMd5Error]
+    # @raise [AwsActionError]
     def post_message(object)
       client.send_message(url, JSON.dump(object))
     end
 
     # Retrieve a message from the queue. Returns nil if no message is waiting
     # in the given poll time. Otherwise it returns a Message.
+    #
+    # @param [Fixnum] poll_time
+    # @return [Message,nil]
+    # @raise [AwsActionError]
     def retrieve(poll_time = 1)
       response = client.receive_message(url, {"WaitTimeSeconds" => poll_time, "MaxNumberOfMessages" => 1})
       raise QueueNotFound.new(self, "not found at #{url}") if response.http_response.status == 404
@@ -123,6 +140,10 @@ module Bisques
 
     # Retrieve a single message from the queue. This will block until a message
     # arrives. The message will be of the class Message.
+    #
+    # @param [Fixnum] poll_time
+    # @return [Message]
+    # @raise [AwsActionError]
     def retrieve_one(poll_time = 5)
       object = nil
       while object.nil?
@@ -134,6 +155,10 @@ module Bisques
     # Delete a message from the queue. This should be called to confirm that
     # the message has been processed. If it is not called then the message will
     # get put back on the queue after a timeout.
+    #
+    # @param [String] handle
+    # @return [Boolean] true if the message was deleted.
+    # @raise [AwsActionError]
     def delete_message(handle)
       response = client.delete_message(url, handle)
       response.success?
@@ -141,6 +166,10 @@ module Bisques
 
     # Return a message to the queue after receiving it. This would typically
     # happen if the receiver decided it couldn't process.
+    #
+    # @param [String] handle
+    # @return [AwsResponse]
+    # @raise [AwsActionError]
     def return_message(handle)
       client.change_message_visibility(url, handle, 0)
     end

data/lib/bisques/queue_listener.rb

@@ -4,17 +4,20 @@ require 'thread'
 module Bisques
   # Listen for messages on a queue and execute a block when they arrive.
   class QueueListener
+    # @param [Queue] queue the queue to listen on
+    # @param [Fixnum] poll_time the number of seconds to long poll during each iteration. Maximum is 20.
     def initialize(queue, poll_time = 5)
       @queue, @poll_time = queue, poll_time
     end
 
+    # @return [Boolean] returns true while the listener is active.
     def listening?
       @listening
     end
 
     # Listen for messages. This is asynchronous and returns immediately.
     #
-    # Ex:
+    # @example
     #
     #   queue = bisques.find_or_create_queue("my queue")
     #   listener = QueuedListener.new(queue)
@@ -25,7 +28,8 @@ module Bisques
     #
     #   while true; sleep 1; end # Process messages forever
     #
-    # Note that the block you give to this method is executed in a new thread.
+    # @note Note that the block you give to this method is executed in a new thread.
+    # @yield [Message] a message received from the {Queue}
     #
     def listen(&block)
       return if @listening
@@ -39,7 +43,7 @@ module Bisques
       end
     end
 
-    # Stop listening for messages
+    # Stop listening for messages.
     def stop
       @listening = false
       @thread.join if @thread
@@ -47,9 +51,9 @@ module Bisques
   end
 
   # Listen for messages on several queues at the same time. The interface for
-  # objects of this class is identical to that of QueueListener.
+  # objects of this class is identical to that of {QueueListener}.
   #
-  # Ex:
+  # @example
   #
   #   queue_1 = bisques.find_or_create_queue("queue one")
   #   queue_2 = bisques.find_or_create_queue("queue two")
@@ -61,15 +65,18 @@ module Bisques
   #   while true; sleep 1; end # Process messages forever
   #
   class MultiQueueListener
+    # @param [Array<Queue>] queues
     def initialize(*queues)
       @queues = queues
       @listeners = []
     end
 
+    # (see QueueListener#listening?)
     def listening?
       @listeners.any?
     end
 
+    # (see QueueListener#listen)
     def listen(&block)
       return if @listeners.any?
       @listeners = @queues.map do |queue|
@@ -81,6 +88,7 @@ module Bisques
       end
     end
 
+    # (see QueueListener#stop)
     def stop
       @listeners.each(&:stop)
       @listeners = []

metadata

@@ -1,96 +1,96 @@
 --- !ruby/object:Gem::Specification
 name: bisques
 version: !ruby/object:Gem::Version
-  version: 1.0.1
   prerelease: 
+  version: 1.0.2
 platform: ruby
 authors:
 - Jeremy Wells
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-31 00:00:00.000000000 Z
+date: 2013-04-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httpclient
-  prerelease: false
+  type: :runtime
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
     none: false
-  type: :runtime
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
     none: false
+  prerelease: false
 - !ruby/object:Gem::Dependency
   name: addressable
-  prerelease: false
+  type: :runtime
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
     none: false
-  type: :runtime
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
     none: false
+  prerelease: false
 - !ruby/object:Gem::Dependency
   name: nokogiri
-  prerelease: false
+  type: :runtime
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
     none: false
-  type: :runtime
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
     none: false
+  prerelease: false
 - !ruby/object:Gem::Dependency
   name: json
-  prerelease: false
+  type: :runtime
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
     none: false
-  type: :runtime
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
     none: false
+  prerelease: false
 - !ruby/object:Gem::Dependency
   name: rspec
-  prerelease: false
+  type: :development
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
     none: false
-  type: :development
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
     none: false
+  prerelease: false
 description: AWS SQS client
 email: jemmyw@gmail.com
 executables: []
@@ -99,6 +99,8 @@ extra_rdoc_files:
 - README.rdoc
 files:
 - README.rdoc
+- LICENSE
+- CHANGELOG
 - Rakefile
 - lib/bisques/aws_connection.rb
 - lib/bisques/aws_credentials.rb
@@ -122,17 +124,23 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
+      segments:
+      - 0
+      hash: -1167259765523084286
       version: '0'
   none: false
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
+      segments:
+      - 0
+      hash: -1167259765523084286
       version: '0'
   none: false
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 1.8.25
 signing_key: 
 specification_version: 3
 summary: AWS SQS client