bunny 0.9.0.pre6 → 0.9.0.pre7

data/lib/bunny/channel_id_allocator.rb

@@ -8,6 +8,7 @@ module Bunny
     # API
     #
 
+    # @param [Integer] max_channel Max allowed channel id
     def initialize(max_channel = ((1 << 16) - 1))
       @int_allocator ||= AMQ::IntAllocator.new(1, max_channel)
 
@@ -29,7 +30,7 @@ module Bunny
 
     # Releases previously allocated channel id. This method is thread safe.
     #
-    # @param [Fixnum] Channel id to release
+    # @param [Fixnum] i Channel id to release
     # @api public
     # @see ChannelManager#next_channel_id
     # @see ChannelManager#reset_channel_id_allocator
@@ -40,6 +41,14 @@ module Bunny
     end # self.release_channel_id(i)
 
 
+    # Returns true if given channel id has been previously allocated and not yet released.
+    # This method is thread safe.
+    #
+    # @param [Fixnum] i Channel id to check
+    # @return [Boolean] true if given channel id has been previously allocated and not yet released
+    # @api public
+    # @see ChannelManager#next_channel_id
+    # @see ChannelManager#release_channel_id
     def allocated_channel_id?(i)
       @channel_id_mutex.synchronize do
         @int_allocator.allocated?(i)

data/lib/bunny/consumer.rb

@@ -1,4 +1,13 @@
 module Bunny
+  # Base class that represents consumer interface. Subclasses of this class implement
+  # specific logic of handling consumer life cycle events. Note that when the only event
+  # you are interested in is message deliveries, it is recommended to just use
+  # {Bunny::Queue#subscribe} instead of subclassing this class.
+  #
+  # @see Bunny::Queue#subscribe
+  # @see Bunny::Queue#subscribe_with
+  # @see http://rubybunny.info/articles/queues.html Queues and Consumers guide
+  # @api public
   class Consumer
 
     #
@@ -13,7 +22,15 @@ module Bunny
     attr_reader   :exclusive
 
 
-
+    # @param [Bunny::Channel] channel Channel this consumer will use
+    # @param [Bunny::Queue,String] queue Queue messages will be consumed from
+    # @param [String] consumer_tag Consumer tag (unique identifier). Generally it is better to let Bunny generate one.
+    #                              Empty string means RabbitMQ will generate consumer tag.
+    # @param [Boolean] no_ack (false) If false, delivered messages will be automatically acknowledged.
+    #                                 If true, manual acknowledgements will be necessary.
+    # @param [Boolean] exclusive (false) Should this consumer be exclusive?
+    # @param [Hash] arguments (nil) Optional arguments that may be used by RabbitMQ extensions, etc
+    # @api public
     def initialize(channel, queue, consumer_tag = channel.generate_consumer_tag, no_ack = true, exclusive = false, arguments = {})
       @channel       = channel || raise(ArgumentError, "channel is nil")
       @queue         = queue   || raise(ArgumentError, "queue is nil")
@@ -23,34 +40,41 @@ module Bunny
       @no_ack        = no_ack
     end
 
-
+    # Defines message delivery handler
+    # @api public
     def on_delivery(&block)
       @on_delivery = block
       self
     end
 
+    # Invokes message delivery handler
+    # @private
     def call(*args)
       @on_delivery.call(*args) if @on_delivery
     end
     alias handle_delivery call
 
+    # Defines consumer cancellation notification handler
+    #
+    # @see http://rubybunny.info/articles/queues.html Queues and Consumers guide
+    # @see http://rubybunny.info/articles/extensions.html RabbitMQ Extensions guide
+    # @api public
     def on_cancellation(&block)
       @on_cancellation = block
       self
     end
 
+    # Invokes consumer cancellation notification handler
+    # @private
     def handle_cancellation(basic_cancel)
       @on_cancellation.call(basic_cancel) if @on_cancellation
     end
 
-    def queue_name
-      if @queue.respond_to?(:name)
-        @queue.name
-      else
-        @queue
-      end
-    end
-
+    # Cancels this consumer. Messages for this consumer will no longer be delivered. If the queue
+    # it was on is auto-deleted and this consumer was the last one, the queue will be deleted.
+    #
+    # @see http://rubybunny.info/articles/queues.html Queues and Consumers guide
+    # @api public
     def cancel
       @channel.basic_cancel(@consumer_tag)
     end
@@ -63,8 +87,18 @@ module Bunny
     # Recovery
     #
 
+    # @private
     def recover_from_network_failure
       @channel.basic_consume_with(self)
     end
+
+    # @private
+    def queue_name
+      if @queue.respond_to?(:name)
+        @queue.name
+      else
+        @queue
+      end
+    end
   end
 end

data/lib/bunny/exceptions.rb

@@ -136,4 +136,13 @@ module Bunny
 
   class UnexpectedFrame < ConnectionLevelException
   end
+
+  class NetworkErrorWrapper < StandardError
+    attr_reader :other
+
+    def initialize(other)
+      super(other.message)
+      @other = other
+    end
+  end
 end

data/lib/bunny/exchange.rb

@@ -1,6 +1,10 @@
 require "bunny/compatibility"
 
 module Bunny
+  # Represents AMQP 0.9.1 exchanges.
+  #
+  # @see http://rubybunny.info/articles/exchanges.html Exchanges and Publishing guide
+  # @see http://rubybunny.info/articles/extensions.html RabbitMQ Extensions guide
   class Exchange
 
     include Bunny::Compatibility
@@ -36,15 +40,16 @@ module Bunny
     # a routing key of "weather.usa.ca.sandiego" and there is a queue Q with this name,
     # that message will be routed to Q.
     #
-    # @param [Bunny::Channel] channel Channel to use.
+    # @param [Bunny::Channel] channel_or_connection Channel to use. {Bunny::Session} instances
+    #                                               are only supported for backwards compatibility.
     #
     # @example Publishing a messages to the tasks queue
     #   channel     = Bunny::Channel.new(connection)
     #   tasks_queue = channel.queue("tasks")
     #   Bunny::Exchange.default(channel).publish("make clean", routing_key => "tasks")
     #
-    # @see Exchange
-    # @see http://files.travis-ci.org/docs/amqp/0.9.1/AMQP091Specification.pdf AMQP 0.9.1 specification (Section 2.1.2.4)
+    # @see http://rubybunny.info/articles/exchanges.html Exchanges and Publishing guide
+    # @see http://www.rabbitmq.com/resources/specs/amqp0-9-1.pdf AMQP 0.9.1 specification (Section 2.1.2.4)
     # @note Do not confuse default exchange with amq.direct: amq.direct is a pre-defined direct
     #       exchange that doesn't have any special routing semantics.
     # @return [Exchange] An instance that corresponds to the default exchange (of type direct).
@@ -53,7 +58,23 @@ module Bunny
       self.new(channel_from(channel_or_connection), :direct, AMQ::Protocol::EMPTY_STRING, :no_declare => true)
     end
 
-
+    # @param [Bunny::Channel] channel_or_connection Channel this exchange will use. {Bunny::Session} instances are supported only for
+    #                                               backwards compatibility with 0.8.
+    # @param [Symbol,String] type                   Exchange type
+    # @param [String] name                          Exchange name
+    # @param [Hash] opts                            Exchange properties
+    #
+    # @option opts [Boolean] :durable (false)      Should this exchange be durable?
+    # @option opts [Boolean] :auto_delete (false)  Should this exchange be automatically deleted when it is no longer used?
+    # @option opts [Boolean] :arguments ({})       Additional optional arguments (typically used by RabbitMQ extensions and plugins)
+    #
+    # @see Bunny::Channel#topic
+    # @see Bunny::Channel#fanout
+    # @see Bunny::Channel#direct
+    # @see Bunny::Channel#headers
+    # @see http://rubybunny.info/articles/exchanges.html Exchanges and Publishing guide
+    # @see http://rubybunny.info/articles/extensions.html RabbitMQ Extensions guide
+    # @api public
     def initialize(channel_or_connection, type, name, opts = {})
       # old Bunny versions pass a connection here. In that case,
       # we just use default channel from it. MK.
@@ -66,7 +87,7 @@ module Bunny
       @auto_delete      = @options[:auto_delete]
       @arguments        = @options[:arguments]
 
-      declare! unless opts[:no_declare] || (@name =~ /^amq\.(direct|fanout|topic|match|headers)/) || (@name == AMQ::Protocol::EMPTY_STRING)
+      declare! unless opts[:no_declare] || predeclared? || (@name == AMQ::Protocol::EMPTY_STRING)
 
       @channel.register_exchange(self)
     end
@@ -83,15 +104,36 @@ module Bunny
       @auto_delete
     end # auto_delete?
 
+    # @return [Hash] Additional optional arguments (typically used by RabbitMQ extensions and plugins)
+    # @api public
     def arguments
       @arguments
     end
 
-    def predeclared?
-      @name == AMQ::Protocol::EMPTY_STRING || (@name =~ /^amq\.(direct|fanout|topic|match|headers)/)
-    end
-
 
+    # Publishes a message
+    #
+    # @param [String] payload Message payload. It will never be modified by Bunny or RabbitMQ in any way.
+    # @param [Hash] opts Message properties (metadata) and delivery settings
+    #
+    # @option opts [String] :routing_key Routing key
+    # @option opts [Boolean] :persistent Should the message be persisted to disk?
+    # @option opts [Boolean] :mandatory Should the message be returned if it cannot be routed to any queue?
+    # @option opts [Integer] :timestamp A timestamp associated with this message
+    # @option opts [Integer] :expiration Expiration time after which the message will be deleted
+    # @option opts [String] :type Message type, e.g. what type of event or command this message represents. Can be any string
+    # @option opts [String] :reply_to Queue name other apps should send the response to
+    # @option opts [String] :content_type Message content type (e.g. application/json)
+    # @option opts [String] :content_encoding Message content encoding (e.g. gzip)
+    # @option opts [String] :correlation_id Message correlated to this one, e.g. what request this message is a reply for
+    # @option opts [Integer] :priority Message priority, 0 to 9. Not used by RabbitMQ, only applications
+    # @option opts [String] :message_id Any message identifier
+    # @option opts [String] :user_id Optional user ID. Verified by RabbitMQ against the actual connection username
+    # @option opts [String] :app_id Optional application ID
+    #
+    # @return [Bunny::Exchange] Self
+    # @see http://rubybunny.info/articles/exchanges.html Exchanges and Publishing guide
+    # @api public
     def publish(payload, opts = {})
       @channel.basic_publish(payload, self.name, (opts.delete(:routing_key) || opts.delete(:key)), opts)
 
@@ -100,32 +142,67 @@ module Bunny
 
 
     # Deletes the exchange unless it is a default exchange
+    #
+    # @param [Hash] opts Options
+    #
+    # @option opts [Boolean] if_unused (false) Should this exchange be deleted only if it is no longer used
+    #
+    # @see http://rubybunny.info/articles/exchanges.html Exchanges and Publishing guide
     # @api public
     def delete(opts = {})
       @channel.deregister_exchange(self)
       @channel.exchange_delete(@name, opts) unless predeclared?
     end
 
-
+    # Binds an exchange to another (source) exchange using exchange.bind AMQP 0.9.1 extension
+    # that RabbitMQ provides.
+    #
+    # @param [String] source Source exchange name
+    # @param [Hash] opts Options
+    #
+    # @option opts [String] routing_key (nil) Routing key used for binding
+    # @option opts [Hash] arguments ({}) Optional arguments
+    #
+    # @return [Bunny::Exchange] Self
+    # @see http://rubybunny.info/articles/exchanges.html Exchanges and Publishing guide
+    # @see http://rubybunny.info/articles/bindings.html Bindings guide
+    # @see http://rubybunny.info/articles/extensions.html RabbitMQ Extensions guide
+    # @api public
     def bind(source, opts = {})
       @channel.exchange_bind(source, self, opts)
 
       self
     end
 
+    # Unbinds an exchange from another (source) exchange using exchange.unbind AMQP 0.9.1 extension
+    # that RabbitMQ provides.
+    #
+    # @param [String] source Source exchange name
+    # @param [Hash] opts Options
+    #
+    # @option opts [String] routing_key (nil) Routing key used for binding
+    # @option opts [Hash] arguments ({}) Optional arguments
+    #
+    # @return [Bunny::Exchange] Self
+    # @see http://rubybunny.info/articles/exchanges.html Exchanges and Publishing guide
+    # @see http://rubybunny.info/articles/bindings.html Bindings guide
+    # @see http://rubybunny.info/articles/extensions.html RabbitMQ Extensions guide
+    # @api public
     def unbind(source, opts = {})
       @channel.exchange_unbind(source, self, opts)
 
       self
     end
 
-
+    # Defines a block that will handle returned messages
+    # @see http://rubybunny.info/articles/exchanges.html
     def on_return(&block)
       @on_return = block
 
       self
     end
 
+    # @private
     def recover_from_network_failure
       # puts "Recovering exchange #{@name} from network failure"
       declare! unless predefined?
@@ -136,6 +213,7 @@ module Bunny
     # Implementation
     #
 
+    # @private
     def handle_return(basic_return, properties, content)
       if @on_return
         @on_return.call(basic_return, properties, content)
@@ -146,8 +224,9 @@ module Bunny
 
     # @return [Boolean] true if this exchange is a pre-defined one (amq.direct, amq.fanout, amq.match and so on)
     def predefined?
-      @name && ((@name == AMQ::Protocol::EMPTY_STRING) || !!(@name =~ /^amq\./i))
+      (@name == AMQ::Protocol::EMPTY_STRING) || !!(@name =~ /^amq\.(direct|fanout|topic|headers|match)/i)
     end # predefined?
+    alias predeclared? predefined?
 
     protected
 

data/lib/bunny/main_loop.rb

@@ -16,6 +16,7 @@ module Bunny
 
     def start
       @thread    = Thread.new(&method(:run_loop))
+      @thread.abort_on_exception = true
     end
 
     def resume
@@ -27,29 +28,7 @@ module Bunny
       loop do
         begin
           break if @stopping || @network_is_down
-
-          frame = @transport.read_next_frame
-          @session.signal_activity!
-
-          next if frame.is_a?(AMQ::Protocol::HeartbeatFrame)
-
-          if !frame.final? || frame.method_class.has_content?
-            header   = @transport.read_next_frame
-            content  = ''
-
-            if header.body_size > 0
-              loop do
-                body_frame = @transport.read_next_frame
-                content << body_frame.decode_payload
-
-                break if content.bytesize >= header.body_size
-              end
-            end
-
-            @session.handle_frameset(frame.channel, [frame.decode_payload, header.decode_payload, content])
-          else
-            @session.handle_frame(frame.channel, frame.decode_payload)
-          end
+          run_once
         rescue Timeout::Error => te
           # given that the server may be pushing data to us, timeout detection/handling
           # should happen per operation and not in this loop
@@ -67,6 +46,31 @@ module Bunny
       end
     end
 
+    def run_once
+      frame = @transport.read_next_frame
+      @session.signal_activity!
+
+      return if frame.is_a?(AMQ::Protocol::HeartbeatFrame)
+
+      if !frame.final? || frame.method_class.has_content?
+        header   = @transport.read_next_frame
+        content  = ''
+
+        if header.body_size > 0
+          loop do
+            body_frame = @transport.read_next_frame
+            content << body_frame.decode_payload
+
+            break if content.bytesize >= header.body_size
+          end
+        end
+
+        @session.handle_frameset(frame.channel, [frame.decode_payload, header.decode_payload, content])
+      else
+        @session.handle_frame(frame.channel, frame.decode_payload)
+      end
+    end
+
     def stop
       @stopping = true
     end

data/lib/bunny/queue.rb

@@ -1,6 +1,10 @@
 require "bunny/compatibility"
 
 module Bunny
+  # Represents AMQP 0.9.1 queue.
+  #
+  # @see http://rubybunny.info/articles/queues.html Queues and Consumers guide
+  # @see http://rubybunny.info/articles/extensions.html RabbitMQ Extensions guide
   class Queue
 
     include Bunny::Compatibility
@@ -10,8 +14,27 @@ module Bunny
     # API
     #
 
-    attr_reader :channel, :name, :options
-
+    # @return [Bunny::Channel] Channel this queue uses
+    attr_reader :channel
+    # @return [String] Queue name
+    attr_reader :name
+    # @return [Hash] Options this queue was created with
+    attr_reader :options
+
+    # @param [Bunny::Channel] channel_or_connection Channel this queue will use. {Bunny::Session} instances are supported only for
+    #                                               backwards compatibility with 0.8.
+    # @param [String] name                          Queue name. Pass an empty string to make RabbitMQ generate a unique one.
+    # @param [Hash] opts                            Queue properties
+    #
+    # @option opts [Boolean] :durable (false)      Should this queue be durable?
+    # @option opts [Boolean] :auto_delete (false)  Should this queue be automatically deleted when the last consumer disconnects?
+    # @option opts [Boolean] :exclusive (false)    Should this queue be exclusive (only can be used by this connection, removed when the connection is closed)?
+    # @option opts [Boolean] :arguments ({})       Additional optional arguments (typically used by RabbitMQ extensions and plugins)
+    #
+    # @see Bunny::Channel#queue
+    # @see http://rubybunny.info/articles/queues.html Queues and Consumers guide
+    # @see http://rubybunny.info/articles/extensions.html RabbitMQ Extensions guide
+    # @api public
     def initialize(channel_or_connection, name = AMQ::Protocol::EMPTY_STRING, opts = {})
       # old Bunny versions pass a connection here. In that case,
       # we just use default channel from it. MK.
@@ -37,33 +60,50 @@ module Bunny
 
     # @return [Boolean] true if this queue was declared as durable (will survive broker restart).
     # @api public
+    # @see http://rubybunny.info/articles/queues.html Queues and Consumers guide
     def durable?
       @durable
     end # durable?
 
     # @return [Boolean] true if this queue was declared as exclusive (limited to just one consumer)
     # @api public
+    # @see http://rubybunny.info/articles/queues.html Queues and Consumers guide
     def exclusive?
       @exclusive
     end # exclusive?
 
     # @return [Boolean] true if this queue was declared as automatically deleted (deleted as soon as last consumer unbinds).
     # @api public
+    # @see http://rubybunny.info/articles/queues.html Queues and Consumers guide
     def auto_delete?
       @auto_delete
     end # auto_delete?
 
     # @return [Boolean] true if this queue was declared as server named.
     # @api public
+    # @see http://rubybunny.info/articles/queues.html Queues and Consumers guide
     def server_named?
       @server_named
     end # server_named?
 
+    # @return [Hash] Additional optional arguments (typically used by RabbitMQ extensions and plugins)
+    # @api public
     def arguments
       @arguments
     end
 
 
+    # Binds queue to an exchange
+    #
+    # @param [Bunny::Exchange,String] exchange Exchange to bind to
+    # @param [Hash] opts                       Binding properties
+    #
+    # @option opts [String] :routing_key  Routing key
+    # @option opts [Hash] :arguments ({}) Additional optional binding arguments
+    #
+    # @see http://rubybunny.info/articles/queues.html Queues and Consumers guide
+    # @see http://rubybunny.info/articles/bindings.html Bindings guide
+    # @api public
     def bind(exchange, opts = {})
       @channel.queue_bind(@name, exchange, opts)
 
@@ -82,6 +122,17 @@ module Bunny
       self
     end
 
+    # Unbinds queue from an exchange
+    #
+    # @param [Bunny::Exchange,String] exchange Exchange to unbind from
+    # @param [Hash] opts                       Binding properties
+    #
+    # @option opts [String] :routing_key  Routing key
+    # @option opts [Hash] :arguments ({}) Additional optional binding arguments
+    #
+    # @see http://rubybunny.info/articles/queues.html Queues and Consumers guide
+    # @see http://rubybunny.info/articles/bindings.html Bindings guide
+    # @api public
     def unbind(exchange, opts = {})
       @channel.queue_unbind(@name, exchange, opts)
 
@@ -97,6 +148,19 @@ module Bunny
       self
     end
 
+    # Adds a consumer to the queue (subscribes for message deliveries).
+    #
+    # @param [Hash] opts Options
+    #
+    # @option opts [Boolean] :manual_ack (false) Will this consumer use manual acknowledgements?
+    # @option opts [Boolean] :exclusive (false) Should this consumer be exclusive for this queue?
+    # @option opts [Boolean] :block (false) Should the call block calling thread?
+    # @option opts [#call] :on_cancellation Block to execute when this consumer is cancelled remotely (e.g. via the RabbitMQ Management plugin)
+    # @option opts [String] :consumer_tag Unique consumer identifier. It is usually recommended to let Bunny generate it for you.
+    # @option opts [Hash] :arguments ({}) Additional (optional) arguments, typically used by RabbitMQ extensions
+    #
+    # @see http://rubybunny.info/articles/queues.html Queues and Consumers guide
+    # @api public
     def subscribe(opts = {
                     :consumer_tag    => @channel.generate_consumer_tag,
                     :ack             => false,
@@ -109,10 +173,10 @@ module Bunny
       consumer   = Consumer.new(@channel,
                                 self,
                                 ctag,
-                                !opts[:ack],
+                                !(opts[:ack] || opts[:manual_ack]),
                                 opts[:exclusive],
                                 opts[:arguments])
-      puts "Added consumer #{ctag} on queue #{@name}"
+
       consumer.on_delivery(&block)
       consumer.on_cancellation(&opts[:on_cancellation]) if opts[:on_cancellation]
 
@@ -126,6 +190,15 @@ module Bunny
       consumer
     end
 
+    # Adds a consumer object to the queue (subscribes for message deliveries).
+    #
+    # @param [Bunny::Consumer] consumer a {Bunny::Consumer} subclass that implements consumer interface
+    # @param [Hash] opts Options
+    #
+    # @option opts [Boolean] block (false) Should the call block calling thread?
+    #
+    # @see http://rubybunny.info/articles/queues.html Queues and Consumers guide
+    # @api public
     def subscribe_with(consumer, opts = {:block => false})
       @channel.basic_consume_with(consumer)
 
@@ -133,6 +206,29 @@ module Bunny
       consumer
     end
 
+    # @param [Hash] opts Options
+    #
+    # @option opts [Boolean] block (false) Should the call block calling thread?
+    #
+    # @return [Array] Triple of delivery info, message properties and message content.
+    #                 If the queue is empty, all three will be nils.
+    # @see http://rubybunny.info/articles/queues.html Queues and Consumers guide
+    # @see Bunny::Queue#subscribe
+    # @api public
+    #
+    # @example
+    #   conn = Bunny.new
+    #   conn.start
+    #
+    #   ch   = conn.create_channel
+    #   q = ch.queue("test1")
+    #   x = ch.default_exchange
+    #   x.publish("Hello, everybody!", :routing_key => 'test1')
+    #
+    #   delivery_info, properties, payload = q.pop
+    #
+    #   puts "This is the message: " + payload + "\n\n"
+    #   conn.close
     def pop(opts = {:ack => false}, &block)
       delivery_info, properties, content = @channel.basic_get(@name, opts)
 
@@ -144,6 +240,10 @@ module Bunny
     end
     alias get pop
 
+    # Version of {Bunny::Queue#pop} that returns data in legacy format
+    # (as a hash).
+    # @return [Hash]
+    # @deprecated
     def pop_as_hash(opts = {:ack => false}, &block)
       delivery_info, properties, content = @channel.basic_get(@name, opts)
 
@@ -156,10 +256,12 @@ module Bunny
       end
     end
 
-    # Publishes a message to the queue via default exchange.
+    # Publishes a message to the queue via default exchange. Takes the same arguments
+    # as {Bunny::Exchange#publish}
     #
     # @see Bunny::Exchange#publish
     # @see Bunny::Channel#default_exchange
+    # @see http://rubybunny.info/articles/exchanges.html Exchanges and Publishing guide
     def publish(payload, opts = {})
       @channel.default_exchange.publish(payload, opts.merge(:routing_key => @name))
 
@@ -168,29 +270,44 @@ module Bunny
 
 
     # Deletes the queue
+    #
+    # @param [Hash] opts Options
+    #
+    # @option opts [Boolean] if_unused (false) Should this queue be deleted only if it has no consumers?
+    # @option opts [Boolean] if_empty (false) Should this queue be deleted only if it has no messages?
+    #
+    # @see http://rubybunny.info/articles/queues.html Queues and Consumers guide
     # @api public
     def delete(opts = {})
       @channel.deregister_queue(self)
       @channel.queue_delete(@name, opts)
     end
 
+    # Purges a queue (removes all messages from it)
+    # @see http://rubybunny.info/articles/queues.html Queues and Consumers guide
+    # @api public
     def purge(opts = {})
       @channel.queue_purge(@name, opts)
 
       self
     end
 
+    # @return [Hash] A hash with information about the number of queue messages and consumers
+    # @see #message_count
+    # @see #consumer_count
     def status
       queue_declare_ok = @channel.queue_declare(@name, @options.merge(:passive => true))
       {:message_count => queue_declare_ok.message_count,
         :consumer_count => queue_declare_ok.consumer_count}
     end
 
+    # @return [Integer] How many messages the queue has ready (e.g. not delivered but not unacknowledged)
     def message_count
       s = self.status
       s[:message_count]
     end
 
+    # @return [Integer] How many active consumers the queue has
     def consumer_count
       s = self.status
       s[:consumer_count]
@@ -200,9 +317,8 @@ module Bunny
     # Recovery
     #
 
+    # @private
     def recover_from_network_failure
-      # puts "Recovering queue #{@name} from network failure"
-
       if self.server_named?
         old_name = @name.dup
         @name    = AMQ::Protocol::EMPTY_STRING
@@ -210,17 +326,21 @@ module Bunny
         @channel.deregister_queue_named(old_name)
       end
 
-      declare!
+      # puts "Recovering queue #{@name}"
       begin
+        declare!
+
         @channel.register_queue(self)
       rescue Exception => e
-        puts "Caught #{e.inspect} while registering #{@name}!"
+        puts "Caught #{e.inspect} while redeclaring and registering #{@name}!"
       end
       recover_bindings
     end
 
+    # @private
     def recover_bindings
       @bindings.each do |b|
+        # puts "Recovering binding #{b.inspect}"
         self.bind(b[:exchange], b)
       end
     end