QPID-4568: Improved the Ruby rdocs.

Added more detailed examples. Fixed up the rdoc markups to make the docs
more useful to developers. Added a comprehensive example to the
Qpid::Messaging module rdocs.

git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk/qpid@1443577 13f79535-47bb-0310-9956-ffa450edef68

9 files changed, 416 insertions, 315 deletions

diff --git a/cpp/bindings/qpid/ruby/lib/qpid_messaging.rb b/cpp/bindings/qpid/ruby/lib/qpid_messaging.rb
index a391485a22..d6efc2fd35 100644
--- a/cpp/bindings/qpid/ruby/lib/qpid_messaging.rb
+++ b/cpp/bindings/qpid/ruby/lib/qpid_messaging.rb
@@ -28,3 +28,56 @@ require 'qpid_messaging/receiver'
 require 'qpid_messaging/session'
 require 'qpid_messaging/connection'
 
+module Qpid
+
+  # The Qpid Messaging framework is an enterprise messaging framework
+  # based on the open-source AMQP protocol.
+  #
+  # ==== Example Application
+  #
+  # Here is a simple example application. It creates a link to a broker located
+  # on a system named *broker.myqpiddomain.com*. It then creates a new messaging
+  # queue named "qpid-examples" and publishes a message to it. It then consumes
+  # that same message and closes the connection.
+  #
+  #   require 'rubygems'
+  #   gem 'qpid_messaging'
+  #   require 'qpid_messaging'
+  #
+  #   # create a connection, open it and then create a session named "session1"
+  #   conn = Qpid::Messaging::Connection.new :name => "broker.myqpiddomain.com"
+  #   conn.open
+  #   session = conn.create_session "session1"
+  #
+  #   # create a sender and a receiver
+  #   # the sender marks the queue as one that is deleted when trhe sender disconnects
+  #   send = session.create_sender "qpid-examples;{create:always,delete:always}"
+  #   recv = session.create_receiver "qpid-examples"
+  #
+  #   # create an outgoing message and send it
+  #   outgoing = Qpid::Messaging::Message.new :content => "The time is #{Time.new}"
+  #   sender.send outgoing
+  #
+  #   # set the receiver's capacity to 10 and then check out many messages are pending
+  #   recv.capacity = 10
+  #   puts "There are #{recv.available} messages waiting." # should report 1 message
+  #
+  #   # get the nextwaiting  message, which should be in the local queue now,
+  #   # and output the contents
+  #   incoming = recv.get Qpid::Messaging::Duration::IMMEDIATE
+  #   puts "Received the following message: #{incoming.content}"
+  #   # the output should be the text that was sent earlier
+  #
+  #   # acknowledge the message, letting the sender know the message was received
+  #   puts "The sender currently has #{send.unsettled} message(s) pending."
+  #   # should report 1 unsettled message
+  #   session.acknowledge incoming # acknowledge the received message
+  #   puts "Now sender currently has #{send.unsettled} message(s) pending."
+  #   # should report 0 unsettled messages
+  #
+  #   # close the connection
+  #   conn.close
+  #
+  module Messaging; end
+
+end
diff --git a/cpp/bindings/qpid/ruby/lib/qpid_messaging/address.rb b/cpp/bindings/qpid/ruby/lib/qpid_messaging/address.rb
index cd188b8a2e..1966332fee 100644
--- a/cpp/bindings/qpid/ruby/lib/qpid_messaging/address.rb
+++ b/cpp/bindings/qpid/ruby/lib/qpid_messaging/address.rb
@@ -24,13 +24,17 @@ module Qpid
     # Address represents an address to which messages can be sent or from
     # which they can be received.
     #
-    # An Address can be described using the following pattern:
+    # == The +Address+ String
+    #
+    # An +Address+ can be described using the following pattern:
     #
     # <address> [ / <subject> ] ; [ { <key> : <value> , ... } ]
     #
     # where *address* is a simple name and *subject* is a subject or subject
     # pattern.
     #
+    # === Options
+    #
     # The options, enclosed in curly braces, are key:value pairs delimited by
     # a comma. The values can be nested maps also enclosed in curly braces.
     # Or they can be lists of values, where they are contained within square
@@ -40,44 +44,45 @@ module Qpid
     #
     # The following are the list of supported options:
     #
-    # [:create]
+    # [create]
     #   Indicates if the address should be created; values are *always*,
     #   *never*, *sender* or *reciever*.
     #
-    # [:assert]
+    # [assert]
     #   Indicates whether or not to assert any specified node properties;
     #   values are *always*, *never*, *sender* or *receiver*.
     #
-    # [:delete]
+    # [delete]
     #   Indicates whether or not to delete the addressed node when a sender
     #   or receiver is cancelled; values are *always*, *never*, *sender* or
     #   *receiver*.
     #
-    # [:node]
+    # [node]
     #   A nested map describing properties for the addressed node. Properties
     #   are *type* (*topic* or *queue*), *durable* (a boolean), *x-declare*
     #   (a nested map of amqp 0.10-specific options) and *x-bindings*. (nested
     #   list which specifies a queue, exchange or a binding key and arguments.
     #
-    # [:link]
+    # [link]
     #   A nested map through which properties of the link can be specified;
     #   properties are *durable*, *reliability*, *x-declare*, *x-subscribe*
     #   and *x-bindings*.
     #
-    # [:mode]
+    # [mode]
     #   (*For receivers only*) indicates whether the receiver should consume
     #   or browse messages; values are *consume* (the default) and *browse*.
-    #
     class Address
 
-      # Creates a new +Address+ object from an address string.
+      # Creates a new +Address+ from an address string.
       #
-      # ==== Options
+      # ==== Attributes
       #
-      # * address - the address string
+      # * +address+ - the address string
       #
       # ==== Examples
       #
+      #   # create a new address for a queue named "my-queue" that will
+      #   # be created if it doesn't already exist
       #   addr = Qpid::Messaging::Address.new "my-queue;{create:always}"
       #
       def initialize(address, address_impl = nil)
@@ -92,7 +97,10 @@ module Qpid
       #
       # ==== Examples
       #
-      #   puts "The address name is #{addr.name}."
+      #    # display the name of the address
+      #    addr = Qpid::Messaging::Address.new "foo;{create:always}"
+      #    # outputs the word 'foo'
+      #    puts addr.name
       #
       def name; @address_impl.getName; end
 
@@ -100,6 +108,9 @@ module Qpid
       #
       # ==== Examples
       #
+      #   # create a new address with the name "my-queue"
+      #   addr = Qpid::Messaging::Address.new "my-queue/my-subject;{create:always}"
+      #   # changes the name to "my-new-queue"
       #   addr.name = "my-new-queue"
       #
       def name=(name); @address_impl.setName name; end
@@ -108,7 +119,8 @@ module Qpid
       #
       # ==== Examples
       #
-      #   puts "The subject is #{addr.subject}."
+      #   # creates a new address with the subject "bar"
+      #   addr = Qpid::Messaging::Address.new "my-queue/bar;{create:always}"
       #
       def subject; @address_impl.getSubject; end
 
@@ -116,30 +128,40 @@ module Qpid
       #
       # ==== Examples
       #
-      #   addr.subject = "testing"
+      #   # creates an address with the subject "example"
+      #   addr = Qpid::Messaging::Address.new "my-queue/example;{create:always}"
+      #   # changes the subject to "test"
+      #   addr.subject = "test"
       #
       def subject=(subject); @address_impl.setSubject(subject); end
 
       # Returns the type for the +Address+.
-      #
-      # ==== Examples
-      #
-      #   puts "The address is a #{address.address_type}."
-      #
-      #---
+      #--
       # We cannot use "type" since that clashes with the Ruby object.type
       # identifier.
+      #++
       def address_type; @address_impl.getType; end
 
       # Sets the type for the +Address+.
       #
       # The type of the address determines how +Sender+ and +Receiver+ objects
-      # are constructed for it. If no type is specified then it will be
-      # determined by querying the broker.
+      # are constructed for it. It also affects how a reply-to address is
+      # encoded.
       #
-      # ===== Options
+      # If no type is specified then it will be determined by querying the
+      # broker. Explicitly setting the type prevents this.
       #
-      # * type - the address type
+      # Values are either *queue* or *topic*.
+      #
+      # ==== Options
+      #
+      # * +type+ - the address type
+      #
+      # ==== Examples
+      #
+      #   # creates an queue address
+      #   addr = Qpid::Messaging::Address.new "my-queue;{create:always}"
+      #   addr.address_type = "queue"
       #
       def address_type=(type); @address_impl.setType(type); end
 
@@ -153,6 +175,7 @@ module Qpid
       # ==== Examples
       #
       #   addr.options = :create => :always
+      #   addr.options = :create => :always, :delete => :always
       #
       def options=(options = {}); @address_impl.setOptions(convert_options(options)); end
 
diff --git a/cpp/bindings/qpid/ruby/lib/qpid_messaging/connection.rb b/cpp/bindings/qpid/ruby/lib/qpid_messaging/connection.rb
index be11e95dfd..6d637a1665 100644
--- a/cpp/bindings/qpid/ruby/lib/qpid_messaging/connection.rb
+++ b/cpp/bindings/qpid/ruby/lib/qpid_messaging/connection.rb
@@ -21,50 +21,53 @@ module Qpid
 
   module Messaging
 
-    # Establishes a connection to a remote endpoint.
+    # A +Connection+ represents a network connection to a remote endpoint.
     class Connection
 
       attr_reader :options # :nodoc:
 
-      # Creates a connection object, but does not actually connect to
-      # the specified location.
+      # Creates a connection object. Raises a MessagingError if an invalid
+      # connection option is used.
       #
-      # ==== Options
+      # == Options
       #
-      #   :url - the URL for the broker (def. +"localhost"+)
-      #   :options - connection options (def. +{}+)
+      # * +:url+ - the URL for the broker
+      # * +:options+ - connection options
       #
-      # ==== Controlling Reconnect Behavior
+      # == Controlling Reconnect Behavior
       #
       # The following connection options can be used to configure
       # the reconnection behavior for this connection.
       #
-      # * :username
-      # * :password
-      # * :heartbeat
-      # * :tcp_nodelay
-      # * :sasl_mechanism
-      # * :sasl_service
-      # * :sasl_min_ssf
-      # * :sasl_max_ssf
-      # * :transport
-      # * :reconnect - +true+ or +false+; indicates wehtehr to attempt reconnections
-      # * :reconnect_timeout - the number of seconds to attempt reconnecting
-      # * :reconnect_limit - the number of retries before reporting failure
-      # * :reconnect_interval_min - initial delay, in seconds, before attempting a reconnection
-      # * :reconnect_interval_max - number of seconds to wait before additional reconnect attempts
-      # * :reconnect_interval - shorthand for setting both min and max values
-      # * :reconnect_urls - a list of alternate URLs to use for reconnection attempts
-      #
-      # ==== Examples
+      # * +:username+ - the authentication username
+      # * +:password+ - the authentication password
+      # * +:heartbeat+
+      # * +:tcp_nodelay+
+      # * +:sasl_mechanism+
+      # * +:sasl_service+
+      # * +:sasl_min_ssf+
+      # * +:sasl_max_ssf+
+      # * +:transport+
+      # * +:reconnect+ - indicates whether to attempt reconnections
+      # * +:reconnect_timeout+ - the number of seconds to attempt reconnecting
+      # * +:reconnect_limit+ - the number of retries before reporting failure
+      # * +:reconnect_interval_min+ - initial delay, in seconds, before attempting a reconnection
+      # * +:reconnect_interval_max+ - number of seconds to wait before additional reconnect attempts
+      # * +:reconnect_interval+ - shorthand for setting both min and max values
+      # * +:reconnect_urls+ - a list of alternate URLs to use for reconnection attempts
+      #
+      # == Examples
       #
+      #   # creates a connection to the broker running local *localhost*
       #   conn = Qpid::Messaging::Connnection.new
+      #   # creates a connection to *broker1.domain.com* on port *5672*
       #   conn = Qpid::Messaging::Connection.new :url => "amqp:tcp:broker1.domain.com:5672"
+      #   # creates a connection to localhost with the specified authentication credentials
       #   conn = Qpid::Messaging::Connection.new :options => {:username => "login", :password => "password"}
       #
       def initialize(opts = {})
         @url = opts[:url] || "localhost"
-        @options = convert_options(opts[:options] || {})
+        @options = Qpid::Messaging.stringify(opts[:options] || {})
         @connection_impl = opts[:impl] || Cqpid::Connection.new(@url, @options)
       end
 
@@ -74,8 +77,9 @@ module Qpid
 
       # Establishes the connection.
       #
-      # ==== Examples
+      # == Examples
       #
+      #   # open a connection if it's not already open
       #   conn.open unless conn.open?
       #
       def open
@@ -84,25 +88,34 @@ module Qpid
 
       # Reports whether the connection is open.
       #
-      # ==== Examples
+      # == Examples
       #
+      #   # close the connection if it's not already closed
       #   conn.close if conn.open?
       #
       def open?; true && !@connection_impl.nil? && @connection_impl.isOpen; end
 
       # Closes the connection.
+      #
+      # == Examples
+      #
+      #   # close a connection
+      #   conn.close
+      #
       def close; @connection_impl.close; end
 
       # Creates a new session.
       #
-      # ==== Arguments
+      # == Arguments
       #
-      # * :name - specifies the name for this session
-      # * :transactional - if +true+ then a creates a transaction session (def. +false+)
+      # * +:name+ - specifies the name for this session
+      # * +:transactional+ - if +true+ then a creates a transaction session (def. +false+)
       #
-      # ==== Examples
+      # == Examples
       #
+      #   # create a session named 'session1'
       #   session = conn.create_session :name => "session1"
+      #   # create a transactional session
       #   session = conn.create_session :transaction => true
       #
       def create_session(args = {})
@@ -119,17 +132,18 @@ module Qpid
         end
       end
 
-      # Returns a Session with the given name.
+      # Returns a Session with the given name. Raises an exception if no
+      # session with the given name exists.
       #
-      # If no such Session exists then a MessagingException is raised.
       # == Options
       #
-      # * +name+ - the session name
+      # * +name+ - the existing session's name
       #
       # == Examples
       #
       #   # retrieve a session named 'mysession' from the current connection
       #   name = "my-session"
+      #   # if no such session exists then catchh the exception raised
       #   begin
       #     session = conn.session name
       #   rescue MessagingException => error
@@ -142,6 +156,18 @@ module Qpid
       end
 
       # Returns the username used to authenticate with the connection.
+      #
+      # If the connection did not user authentication credentials, then the
+      # username returned is "anonymous".
+      #
+      # == Examples
+      #
+      #   # create a new connection for user "qpiduser"
+      #   conn = Qpid::Messaging::Connection.new :username => "qpiduser"
+      #   conn.open
+      #   # displays the authenticate username
+      #   puts "Connected as #{conn.authenticated_username}" # should say 'qpiduser'
+      #
       def authenticated_username; @connection_impl.getAuthenticatedUsername if open?; end
 
       private
diff --git a/cpp/bindings/qpid/ruby/lib/qpid_messaging/duration.rb b/cpp/bindings/qpid/ruby/lib/qpid_messaging/duration.rb
index 544bbd2156..11c903dade 100644
--- a/cpp/bindings/qpid/ruby/lib/qpid_messaging/duration.rb
+++ b/cpp/bindings/qpid/ruby/lib/qpid_messaging/duration.rb
@@ -23,19 +23,21 @@ module Qpid
 
     # A Duration represents a period of time in milliseconds
     #
-    # It defines the following named values as symbols:
+    # == Named Durations
     #
-    # [:FOREVER]
+    # The following named +Durations+ are available as symbols:
+    #
+    # [FOREVER]
     #   The maximum integer value for the platform. Effectively this will wait
     #   forever.
     #
-    # [:IMMEDIATE]
+    # [IMMEDIATE]
     #   An alias for 0 milliseconds.
     #
-    # [:SECOND]
+    # [SECOND]
     #   An alias for 1,000 milliseconds.
     #
-    # [:MINUTE]
+    # [MINUTE]
     #   And alias for 60,000 millisecons.
     #
     class Duration
@@ -44,12 +46,13 @@ module Qpid
       #
       # ==== Options
       #
-      # * length - The duration in milliseconds.
+      # * +length+ - The duration in +milliseconds+.
       #
       # ==== Examples
       #
-      #   # Wait up to 10 seconds for an incoming message
-      #   receiver.get Qpid::Messaging::Duration.new 10000
+      #   # creates a duration of 15 seconds
+      #   # REMEMBER: Duration deals in milliseconds
+      #   delay = Qpid::Messaging::Duration.new 15000
       #
       def initialize length
         @duration_impl = Cqpid::Duration.new length
@@ -59,26 +62,42 @@ module Qpid
         @duration_impl
       end
 
-      # Returns the period of time in milliseconds
+      # Returns the period of time in +milliseconds+.
       #
       # ==== Examples
       #
-      #   duration = Qpid::Messaging::Duration.new :length => 5000
-      #   puts "Waiting #{duration.milliseconds} ms for a message."
-      #   msg = receiver.fetch duration
+      #   # doubling growth in waiting for messages in a loop
+      #   do loop
+      #     set the base duration waiting length
+      #     timeout = Qpid::Messaging::Duration::SECOND
+      #     msg = nil
+      #     # loop until we receive a message
+      #     while msg.nil?
+      #       puts "Waiting #{timeout.milliseconds}ms"
+      #       msg = recv.get timeout
+      #       # if nothing was received, double the duration
+      #       if msg.nil?
+      #         # double out timeout
+      #         timeout = timeout * 2
+      #       else
+      #         # do something with the message
+      #         puts "Received: #{msg.content}"
+      #       end
+      #     end
+      #   end
       #
       def milliseconds
         @duration_impl.getMilliseconds
       end
 
-      # Returns a new Duration with a period of time that is a multiple
-      # of the original Duration.
+      # Multiplies the duration of the +Duration+ and returns a new instance.
       #
       # Raises exceptions on a negative factor. Returns
       # Qpid::Messaging::Duration::IMMEDIATE when the factor is 0.
       #
       # ==== Examples
       #
+      #   # return a duration that is 2 minutes (120,000 ms)
       #   twominutes = Qpid::Messaging::Duration::MINUTE * 2
       #
       def *(factor)
diff --git a/cpp/bindings/qpid/ruby/lib/qpid_messaging/encoding.rb b/cpp/bindings/qpid/ruby/lib/qpid_messaging/encoding.rb
index db163fb3b8..ac0fbc32a7 100644
--- a/cpp/bindings/qpid/ruby/lib/qpid_messaging/encoding.rb
+++ b/cpp/bindings/qpid/ruby/lib/qpid_messaging/encoding.rb
@@ -22,12 +22,12 @@ module Qpid
   module Messaging
 
     # Encodes the supplied content into the given message.
-    def self.encode content, message, encoding = nil
+    def self.encode content, message, encoding = nil # :nodoc:
       Cqpid::encode content, message.message_impl, encoding
     end
 
     # Decodes and returns the message's content.
-    def self.decode(message, content_type = nil)
+    def self.decode(message, content_type = nil) # :nodoc:
       content_type = message.content_type if content_type.nil?
 
       case content_type
@@ -42,7 +42,7 @@ module Qpid
 
     # Takes as input any type and converts anything that's a symbol
     # into a string.
-    def self.stringify(value)
+    def self.stringify(value) # :nodoc:
       # set the default value
       result = value
 
diff --git a/cpp/bindings/qpid/ruby/lib/qpid_messaging/message.rb b/cpp/bindings/qpid/ruby/lib/qpid_messaging/message.rb
index 395680c882..fadb279fbf 100644
--- a/cpp/bindings/qpid/ruby/lib/qpid_messaging/message.rb
+++ b/cpp/bindings/qpid/ruby/lib/qpid_messaging/message.rb
@@ -22,20 +22,19 @@ module Qpid
   module Messaging
 
     # A +Message+ represents an routable piece of information.
-    #
-    # The content for a message is automatically encoded and decoded.
-    #
     class Message
 
-      # Creates a new instance of +Message+.
+      # Creates a +Message+.
       #
       # ==== Options
       #
-      # * :content - The content.
+      # * +:content+ - the content
       #
       # ==== Examples
       #
+      #   # create a simple message and sends it
       #   message = Qpid::Messaging::Message.new :content => "This is a message."
+      #   sender.send message
       #
       def initialize(args = {})
         @message_impl = (args[:impl] if args[:impl]) || nil
@@ -49,15 +48,20 @@ module Qpid
         @message_impl
       end
 
-      # Sets the address to which replies should be sent for the +Message+.
+      # Sets the reply-to address.
+      #
+      # The address can either be an instance of Address or else and
+      # address string.
       #
       # ==== Options
       #
-      # * address - an instance of +Address+, or an address string
+      # * +address+ - the address
       #
       # ==== Examples
       #
+      #   # set replies using an Address
       #   msg.reply_to = Qpid:Messaging::Address.new "my-responses"
+      #   # set replies using an address string
       #   msg.reply_to = "my-feed/responses"
       #
       def reply_to=(address)
@@ -67,7 +71,6 @@ module Qpid
       end
 
       # Returns the reply to address for the +Message+.
-      #
       def reply_to
         address_impl = @message_impl.getReplyTo
         # only return an address if a reply to was specified
@@ -78,25 +81,15 @@ module Qpid
       #
       # ==== Options
       #
-      # * subject - the subject
-      #
-      # ==== Examples
-      #
-      #   msg.subject = "mysubject"
-      #
+      # * +subject+ - the subject
       def subject=(subject); @message_impl.setSubject subject; end
 
       # Returns the subject of the +Message+.
-      #
-      # ==== Options
-      #
-      #   puts "The subject is #{msg.subject}"
-      #
       def subject; @message_impl.getSubject; end
 
       # Sets the content type for the +Message+.
       #
-      # This should be set by the sending applicaton and indicates to
+      # This should be set by the sending applicaton and indicates to the
       # recipients of the message how to interpret or decode the content.
       #
       # By default, only dictionaries and maps are automatically given a content
@@ -105,23 +98,17 @@ module Qpid
       #
       # ==== Options
       #
-      # * content_type - the content type.
-      #
-      def content_type=(content_type); @message_impl.setContentType content_type; end
-
-      # Returns the content type for the +Message+.
+      # * +content_type+ - the content type
       #
       # ==== Examples
       #
-      #   case msg.content_type
-      #     when "myapp/image"
-      #       ctl.handle_image msg
-      #       end
-      #     when "myapp/audio"
-      #       ctl.handle_audio msg
-      #       end
-      #   end
+      #   # send base64 encoded data in a mesage
+      #   msg = Qpid::Messaging::Message.new :content = "UXBpZCBSdWxlcyEK"
+      #   msg.content_type = "application/base64"
       #
+      def content_type=(content_type); @message_impl.setContentType content_type; end
+
+      # Returns the content type for the +Message+.
       def content_type; @message_impl.getContentType; end
 
       # Sets the message id.
@@ -131,16 +118,17 @@ module Qpid
       #
       # ==== Options
       #
-      # * id - the id
+      # * +id+ - the id
       #
       # ==== Examples
       #
+      #   # this example only works in Ruby >= 1.9, for 1.8 use a UUID library
+      #   require 'SecureRandom'
+      #   msg.message_id = SecureRandom.uuid
       #
       def message_id=(message_id); @message_impl.setMessageId message_id.to_s; end
 
       # Returns the message id.
-      #
-      # See +message_id=+ for details.
       def message_id; @message_impl.getMessageId; end
 
       # Sets the user id for the +Message+.
@@ -149,21 +137,18 @@ module Qpid
       # the connection itself, as the messaging infrastructure will verify
       # this.
       #
-      # See +Qpid::Messaging::Connection.authenticated_username+
+      # See Qpid::Messaging::Connection.authenticated_username
       #
       # *NOTE:* If the id is not a +String+ then the id is set using
       # the object's string representation.
       #
       # ==== Options
       #
-      # * id - the id
+      # * +id+ - the id
       #
       def user_id=(user_id); @message_impl.setUserId user_id; end
 
       # Returns the user id for the +Message+.
-      #
-      # See +user_id=+ for details.
-      #
       def user_id; @message_impl.getUserId; end
 
       # Sets the correlation id of the +Message+.
@@ -179,14 +164,11 @@ module Qpid
       #
       # ==== Options
       #
-      # * id - the id
+      # * +id+ - the id
       #
       def correlation_id=(correlation_id); @message_impl.setCorrelationId correlation_id; end
 
       # Returns the correlation id of the +Message+.
-      #
-      # *NOTE:* See +correlation_id=+ for details.
-      #
       def correlation_id; @message_impl.getCorrelationId; end
 
       # Sets the priority of the +Message+.
@@ -200,19 +182,18 @@ module Qpid
       #
       # ==== Options
       #
-      # * priority - the priority
+      # * +priority+ - the priority
       #
       def priority=(priority); @message_impl.setPriority priority; end
 
       # Returns the priority for the +Message+.
-      #
       def priority; @message_impl.getPriority; end
 
       # Sets the time-to-live in milliseconds.
       #
       # ==== Options
       #
-      # * duration - the number of milliseconds
+      # * +duration+ - the number of milliseconds
       #
       def ttl=(duration)
         if duration.is_a? Qpid::Messaging::Duration
@@ -233,12 +214,11 @@ module Qpid
       #
       # ==== Options
       #
-      # * durable - the durability flag (def. false)
+      # * +durable+ - the durability flag (def. false)
       #
       def durable=(durable); @message_impl.setDurable durable; end
 
       # Returns the durability for the +Message+.
-      #
       def durable; @message_impl.getDurable; end
 
       # This is a hint to the messaging infrastructure that if de-duplication
@@ -247,17 +227,16 @@ module Qpid
       #
       # ==== Options
       #
-      # * redelivered - sets the redelivered state (def. false)
+      # * +redelivered+ - sets the redelivered state (def. false)
       #
       # ==== Examples
       #
-      #   # processed is an array of processed message ids
+      #   # processed is a collection of messages already received
       #   msg.redelivered = true if processed.include? msg.message_id
       #
       def redelivered=(redelivered); @message_impl.setRedelivered redelivered; end
 
       # Returns whether the +Message+ has been marked as redelivered.
-      #
       def redelivered; @message_impl.getRedelivered; end
 
       # Returns all named properties.
@@ -265,14 +244,13 @@ module Qpid
       # *NOTE:* It is recommended to use the []= method for
       # retrieving and setting properties. Using this method may
       # result in non-deterministic behavior.
-      #
       def properties; @message_impl.getProperties; end
 
       # Returns the value for the named property.
       #
       # ==== Options
       #
-      # * name - the property name
+      # * +name+ - the property name
       #
       # ==== Examples
       #
@@ -283,10 +261,21 @@ module Qpid
 
       # Assigns a value to the named property.
       #
+      # A property's name or value, if a symbol, will be converted to a string
+      # representation. However, you will still be able to access them using
+      # a symbol for the name.
+      #
       # ==== Options
       #
-      # * name - the property name
-      # * value - the property value
+      # * +name+ - the property name
+      # * +value+ - the property value
+      #
+      # ==== Examples
+      #
+      #   # set the signed attribute on a message and then retrieve it
+      #   msg[:signed] = true # sets "signed" => true
+      #   puts "It's signed" if msg["signed"] # outputs "It's signed"
+      #
       def []=(key, value)
         @message_impl.setProperty(key.to_s,
                                   Qpid::Messaging.stringify(value))
@@ -295,17 +284,19 @@ module Qpid
       # Sets the content for the +Message+.
       #
       # Content is automatically encoded for Array and Hash types. Other types
-      # need to set their own content types (via +content_type+) in order to
+      # need to set their own content types (via content_type) in order to
       # specify how recipients should process the content.
       #
       # ==== Options
       #
-      # * content - the content
+      # * +content+ - the content
       #
       # ==== Examples
       #
-      #   msg.content = "This is a simple message." # a simple message
-      #   msg.content = {:foo => :bar} # content is automatically encoded
+      #   # set a simple content for a message
+      #   msg.content = "This is a simple message."
+      #   # sets content that is automatically encoded
+      #   msg.content = {:foo => :bar}
       #
       def content=(content)
         content_type = nil
@@ -348,8 +339,7 @@ module Qpid
         @content
       end
 
-      # Returns the content's size.
-      #
+      # Returns the content's size in bytes.
       def content_size; @message_impl.getContentSize; end
 
     end
diff --git a/cpp/bindings/qpid/ruby/lib/qpid_messaging/receiver.rb b/cpp/bindings/qpid/ruby/lib/qpid_messaging/receiver.rb
index 00d0efd72c..37dd45a6bd 100644
--- a/cpp/bindings/qpid/ruby/lib/qpid_messaging/receiver.rb
+++ b/cpp/bindings/qpid/ruby/lib/qpid_messaging/receiver.rb
@@ -21,17 +21,26 @@ module Qpid
 
   module Messaging
 
-    # Receiver is the entity through which messages are received.
+    # +Receiver+ is the entity through which messages are received.
     #
-    # An instance of Receiver can only be created using an active (not
-    # previously closed) Session.
+    # An instance of +Receiver+ can only be created using an active (i.e., not
+    # previously closed) Session. See Qpid::Messaging::Session.create_receiver
+    # for more details.
     #
     # ==== Example
     #
+    #   # create a connection and a session
     #   conn     = Qpid::Messaging::Connection.new :url => "mybroker:5762"
     #   conn.open
     #   session  = conn.create_session
-    #   receiver = session.create_receiver "my-sender-queue"
+    #
+    #   # create a receiver that listens on the "updates" topic of "alerts"
+    #   receiver = session.create_receiver "alerts/updates"t
+    #
+    #   # wait for an incoming message and process it
+    #   incoming = receiver.get Qpid::Messaging::Duration::FOREVER
+    #   process(incoming)
+    #
     class Receiver
 
       def initialize(session, receiver_impl) # :nodoc:
@@ -46,27 +55,24 @@ module Qpid
       # Retrieves a message from the local queue, or waits for up to
       # the duration specified for one to become available.
       #
-      # If a block is given, then it will be invaked after the next message
-      # is received or the call times out, passing in the message or nil
-      # respectively.
+      # If no message is received within the specified time then a
+      # MessagingException is raised.
       #
       # ==== Options
-      # * duration - the timeout to wait (def. Duration::FOREVER)
       #
-      # ==== Examples
-      #
-      #   msg = rcvr.get # Uses the default timeout of forever
+      # * duration - the timeout to wait
       #
-      #   msg = rcvr.get Qpid::Messaging::Duration::IMMEDIATE # returns a message or exits immediately
+      # ==== Examples
       #
-      #   # passes in a block to handle the received message
-      #   rcvr.get Qpid::Messaging::Duration::SECOND do |message|
-      #     if message.nil?
-      #       puts "No message was received."
-      #     else
-      #       puts "Received this message: #{message.content}"
-      #     end
+      #   # retrieves a message, also handles exceptions raised on no messages
+      #   begin
+      #     # checks for a message, returning immediately
+      #     msg = recv.get Qpid::Messaging::Duration::IMMEDIATE
+      #     puts "Received this message: #{message.content}"
+      #   rescue
+      #     puts "No messages available.
       #   end
+      #
       def get(duration = Qpid::Messaging::Duration::FOREVER)
         message_impl = @receiver_impl.get duration.duration_impl
         create_message_wrapper message_impl unless message_impl.nil?
@@ -75,33 +81,35 @@ module Qpid
       # Retrieves a message from the receiver's subscription, or waits
       # for up to the duration specified for one to become available.
       #
-      # If a block is given, then it will be invaked after the next message
-      # is received or the call times out, passing in the message or nil
-      # respectively.
+      # If no message is fetched within the specified time then a
+      # MessagingException is raised.
       #
       # ==== Options
+      #
       # * duration - the timeout to wait (def. Duration::FOREVER)
       #
       # ==== Examples
       #
-      #   msg = rcvr.fetch # Uses the default timeout of forever
-      #
-      #   msg = rcvr.fetch Qpid::Messaging::Duration::IMMEDIATE # returns a message or exits immediately
-      #
-      #   # passes in a block to handle the received message
-      #   rcvr.fetch Qpid::Messaging::Duration::SECOND do |message|
-      #     if message.nil?
-      #       puts "No message was received."
-      #     else
-      #       puts "Received this message: #{message.content}"
-      #     end
+      #   # retrieves a message, also handles exceptions raised on no messages
+      #   begin
+      #     # checks for a message, times out after one second
+      #     msg = recv.fetch Qpid::Messaging::Duration::SECOND
+      #     puts "Fetched this message: #{message.content}"
+      #   rescue
+      #     puts "No messages available.
       #   end
+      #
       def fetch(duration = Qpid::Messaging::Duration::FOREVER)
         message_impl = @receiver_impl.fetch duration.duration_impl
         create_message_wrapper message_impl unless message_impl.nil?
       end
 
-      # Sets the capacity for this +Receiver+.
+      # Sets the capacity.
+      #
+      # The capacity of a +Receiver+ is the number of Messages that can be
+      # pre-fetched from the broker and held locally. If capacity is 0 then
+      # messages will never be pre-fetched and all messages must instead be
+      # retrieved using #fetch.
       #
       # ==== Options
       #
@@ -109,63 +117,50 @@ module Qpid
       #
       # ==== Examples
       #
-      #   receiver.capacity = 50 # sets the incoming capacity to 50 messages
+      #   # create a receiver and give it a capacity of 50
+      #   recv = session.create_receiver "alerts/minor"
+      #   recv.capacity = 50
       #
       def capacity=(capacity); @receiver_impl.setCapacity capacity; end
 
       # Returns the capacity.
-      #
-      #
-      # The capacity is the numnber of incoming messages that can be held
-      # locally before being fetched.
-      #
-      # ==== Examples
-      #
-      #   puts "The receiver can hold #{rcv.capacity} messages."
-      #
       def capacity; @receiver_impl.getCapacity; end
 
-      # Returns the number of slots for receiving messages.
+      # Returns the number of messages locally held.
+      #
+      # The available is always 0 <= available <= capacity.
       #
-      # This differs from +capacity+ in that it is the available slots in
-      # the capacity for holding incoming messages, where available <= capacity.
+      # If the #capacity is set to 0 then available will always be 0.
       #
       # ==== Examples
       #
-      #   puts "You can receive #{rcv.available} messages before blocking."
+      #   # output the number of messages waiting while processing
+      #   loop do
+      #     puts "There are #{recv.available} messages pending..."
+      #     # wait forever (the default) for the next message
+      #     msg = recv.get
+      #     # process the message
+      #     dispatch_message msg
+      #   end
       #
       def available; @receiver_impl.getAvailable; end
 
       # Returns the number of messages that have been received and acknowledged
       # but whose acknowledgements have not been confirmed by the sender.
-      #
-      # ==== Examples
-      #
-      #   puts "You have #{rcv.unsettled} messages to be confirmed."
-      #
       def unsettled; @receiver_impl.getUnsettled; end
 
       # Closes this +Receiver+.
       #
-      # This does not affect the +Session+.
+      # This does not affect the owning Session or Connection.
       def close; @receiver_impl.close; end
 
-      # Returns whether the receiver is closed.
-      #
-      # ==== Examples
-      #
-      #   recv.close unless recv.closed?
-      #
+      # Returns whether the +Receiver+ is closed.
       def closed?; @receiver_impl.isClosed; end
 
       # Returns the name of this +Receiver+.
-      #
-      # ==== Examples
-      #
-      #   puts "Receiver: #{recv.name}"
       def name; @receiver_impl.getName; end
 
-      # Returns the Session for this +Receiver+.
+      # Returns the owning Session for this +Receiver+.
       def session; @session; end
 
       private
diff --git a/cpp/bindings/qpid/ruby/lib/qpid_messaging/sender.rb b/cpp/bindings/qpid/ruby/lib/qpid_messaging/sender.rb
index 1e87f9fd8c..d5dbb51926 100644
--- a/cpp/bindings/qpid/ruby/lib/qpid_messaging/sender.rb
+++ b/cpp/bindings/qpid/ruby/lib/qpid_messaging/sender.rb
@@ -21,17 +21,33 @@ module Qpid
 
   module Messaging
 
-    # Sender is the entity through which messages sent.
+    # +Sender+ is the entity through which messages sent.
     #
-    # An instance of Sender can only be created using an active (not previously
-    # closed) Session.
+    # An instance of +Sender+ can only be created using an active (not previously
+    # closed) Session. See Qpid::Messaging::Session.create_sender for more details.
     #
     # ==== Examples
     #
-    #   conn    = Qpid::Messaging::Connection.new :url => "mybroker:5762"
+    #   # create a connection
+    #   conn = Qpid::Messaging::Connection.new "mybroker:5672"
     #   conn.open
-    #   session = conn.create_session
-    #   sender  = session.create_session "my-sender-queue;{create:always}"
+    #
+    #   if conn.open?
+    #
+    #     # create a session
+    #     session = conn.create_session
+    #
+    #     # create a sender that posts messages to the "updates" queue
+    #     sender = session.create_sender "updates;{create:always}
+    #
+    #     # begin sending updates
+    #     loop do
+    #       # wait for the next event content then send it
+    #       content = wait_for_event
+    #       sender.send Qpid::Messaging::Message.new :content => content
+    #     end
+    #   end
+    #
     class Sender
 
       def initialize(session, sender_impl) # :nodoc:
@@ -43,15 +59,13 @@ module Qpid
         @sender_impl
       end
 
-      # Sends a message.
-      #
-      # If a block is given, then it will be invoked after the message
-      # is sent.
+      # Sends a message, optionally blocking until the message is received
+      # by the broker.
       #
       # ==== Options
       #
-      # * message - The message to send.
-      # * :sync - See note below on synching.
+      # * +message+ - The message to send.
+      # * +:sync+ - Block until received. See note below on synching.
       #
       # ==== Synching
       #
@@ -61,9 +75,13 @@ module Qpid
       #
       # ==== Examples
       #
-      #   sender.send message do |message|
-      #     puts "Message sent: #{message.content}"
-      #   end
+      #   # send a message
+      #   outgoing = Qpid::Messaging::Message.new :content => content
+      #   sender.send outgoing
+      #
+      #   # send a message, wait for confirmation from the broker
+      #   outgoing = Qpid::Messaging::Message.new :content => content
+      #   sender.send outgoing, :sync => true
       #
       def send(message, args = {}, &block)
         sync = args[:sync] || false
@@ -73,52 +91,27 @@ module Qpid
 
       # Closes this +Sender+.
       #
-      # This does not affect the +Session+.
+      # This does not affect the owning Session or Connection.
       def close; @sender_impl.close; end
 
       # Returns the human-readable name for this +Sender+.
-      #
-      # ==== Examples
-      #
-      #   puts "Sender: #{sender.name}"
-      #
       def name; @sender_impl.getName; end
 
       # Sets the capacity for this +Sender+.
       #
       # The capacity is the number of outgoing messages that can be held
-      # pending confirmation or receipt by the broker.
+      # pending confirmation of receipt by the broker.
       #
       # ==== Options
       #
-      # * capacity - the capacity
-      #
-      # ==== Examples
-      #
-      #   sender.capacity = 50 # sets the outgoing capacity to 50 messages
-      #
+      # * +capacity+ - the capacity
       def capacity=(capacity); @sender_impl.setCapacity capacity; end
 
       # Returns the capacity.
-      #
-      # The capacity is the total number of outgoing messages that can be
-      # sent before a called to +send+ begins to block by default.
-      #
-      # ==== Examples
-      #
-      #   puts "You can send a maximum of #{sender.capacity} messages."
-      #
       def capacity; @sender_impl.getCapacity; end
 
       # Returns the number of messages sent that are pending receipt
       # confirmation by the broker.
-      #
-      # ==== Examples
-      #
-      #   if sender.unsettled > 0
-      #     puts "There are #{sender.unsettled} messages pending."
-      #   end
-      #
       def unsettled; @sender_impl.getUnsettled; end
 
       # Returns the available slots for sending messages.
@@ -127,21 +120,11 @@ module Qpid
       # the senders capacity for holding outgoing messages. The difference
       # between capacity and available is the number of messages that
       # have not been delivered yet.
-      #
-      # ==== Examples
-      #
-      #   puts "You can send #{sender.available} messages before blocking."
-      #
       def available
         @sender_impl.getAvailable
       end
 
-      # Returns the +Session+ for this sender.
-      #
-      # ==== Examples
-      #
-      #   recv.session.close if done
-      #
+      # Returns the Session for this sender.
       def session; @session; end
 
     end
diff --git a/cpp/bindings/qpid/ruby/lib/qpid_messaging/session.rb b/cpp/bindings/qpid/ruby/lib/qpid_messaging/session.rb
index 2be89dc5b6..7099f79258 100644
--- a/cpp/bindings/qpid/ruby/lib/qpid_messaging/session.rb
+++ b/cpp/bindings/qpid/ruby/lib/qpid_messaging/session.rb
@@ -21,7 +21,11 @@ module Qpid
 
   module Messaging
 
-    # A Session represents a distinct conversation between end points.
+    # A +Session+ represents a distinct conversation between end points. They are
+    # created from an active (i.e., not closed) Connection.
+    #
+    # A +Session+ is used to acknowledge individual or all messages that have
+    # passed through it
     class Session
 
       def initialize(connection, session) # :nodoc:
@@ -33,24 +37,19 @@ module Qpid
         @session_impl
       end
 
-      # Returns the +Connection+ associated with this session.
+      # Returns the Connection associated with this session.
       def connection
         @connection
       end
 
       # Creates a new endpoint for sending messages.
       #
-      # The +address+ can either be an instance +Address+ or else a
-      # string that describes an address endpoint.
+      # The address can either be an instance Address or else an
+      # address string.
       #
       # ==== Arguments
       #
-      # * +address+ The end point address.
-      #
-      # ==== Examples
-      #
-      #   sender = session.create_sender "my-queue;{create:always}"
-      #
+      # * +address+ - the end point address.
       def create_sender(address)
         _address = address
 
@@ -64,35 +63,25 @@ module Qpid
         Qpid::Messaging::Sender.new(self, sender_impl)
       end
 
-      # Retrieves the +Sender+ with the specified name.
+      # Retrieves the Sender with the specified name.
       #
-      # Raises an exception when no such Sender exists.
+      # Raises an exception if no such Sender exists.
       #
       # ==== Arguments
       #
-      # * +name+ The +Sender+ name.
-      #
-      # ==== Examples
-      #
-      #   sender = session.sender "my-queue"
-      #
+      # * +name+ - the name of the Sender
       def sender(name)
         Qpid::Messaging::Sender.new self, @session_impl.getSender(name)
       end
 
       # Creates a new endpoint for receiving messages.
       #
-      # The +address+ can either be an instance +Address+ or else a
-      # string that describes an address endpoint.
+      # The +address+ can either be an instance Address or else an
+      # address string.
       #
       # ==== Arguments
       #
-      # * +address+ The end point address.
-      #
-      # ==== Examples
-      #
-      #   receiver = session.create_receiver "my-queue"
-      #
+      # * +address+ - the end point address.
       def create_receiver(address)
         result        = nil
         receiver_impl = nil
@@ -112,20 +101,16 @@ module Qpid
       #
       # ==== Arguments
       #
-      # * +name+ The +Receiver+ name.
-      #
-      # ==== Examples
-      #
-      #   receiver = session.receiver "my-queue"
-      #
+      # * +name+ - the name of the Receiver
       def receiver(name)
         Qpid::Messaging::Receiver.new self, @session_impl.getReceiver(name)
       end
 
       # Closes the +Session+ and all associated +Sender+ and +Receiver+ instances.
       #
-      # NOTE: All +Session+ instances for a +Connection+ are closed when the
-      # +Connection+ is closed.
+      # *NOTE:* All +Session+ instances for a Connection are closed when the
+      # Connection is closed. But closing a +Session+ does not affect the
+      # owning Connection.
       def close; @session_impl.close; end
 
       # Commits any pending transactions for a transactional session.
@@ -139,21 +124,30 @@ module Qpid
       #
       # ==== Arguments
       #
-      # * :message - if specified, then only the +Message+ specified is acknowledged
-      # * :sync - if true then the call will block until processed by the server (def. false)
+      # * +options+ - the set of options
+      #
+      # ==== Options
+      #
+      # * :message - if specified, then only that Message is acknowledged
+      # * :sync - if true, the call will block until processed by the server
       #
       # ==== Examples
       #
-      #   session.acknowledge                     # acknowledges all received messages
-      #   session.acknowledge :message => message # acknowledge one message
-      #   session.acknowledge :sync => true       # blocks until the call completes
+      #   # acknowledge all received messages
+      #   session.acknowledge
+      #
+      #   # acknowledge a single message
+      #   session.acknowledge :message => message
+      #
+      #   # acknowledge all messages, wait until the call finishes
+      #   session.acknowledge :sync => true
       #
       #--
       # TODO: Add an optional block to be used for blocking calls.
       #++
-      def acknowledge(args = {})
-        sync = args[:sync] || false
-        message = args[:message] if args[:message]
+      def acknowledge(options = {})
+        sync = options[:sync] || false
+        message = options[:message] if options[:message]
 
         unless message.nil?
           @session_impl.acknowledge message.message_impl, sync
@@ -178,7 +172,11 @@ module Qpid
       #
       # ==== Arguments
       #
-      # * :block - if true then the call blocks until the server acknowledges it (def. false)
+      # * +options+ - the list of options
+      #
+      # ==== Options
+      #
+      # * +:block+ - if true, the call blocks until the server acknowledges it
       #
       #--
       # TODO: Add an optional block to be used for blocking calls.
@@ -189,26 +187,43 @@ module Qpid
       end
 
       # Returns the total number of receivable messages, and messages already
-      # received, by +Receiver+ instances associated with this +Session+.
+      # received, by Receiver instances associated with this +Session+.
       def receivable; @session_impl.getReceivable; end
 
-      # Returns the number of messages that have been acknowledged by this session
-      # whose acknowledgements have not been confirmed as processed by the server.
+      # Returns the number of messages that have been acknowledged by this
+      # +Session+ whose acknowledgements have not been confirmed as processed
+      # by the server.
       def unsettled_acks; @session_impl.getUnsettledAcks; end
 
-      # Fetches the +Receiver+ for the next message.
+      # Fetches the next Receiver with a message pending. Waits the specified
+      # number of milliseconds before timing out.
+      #
+      # For a Receiver to be returned, it must have a capacity > 0 and have
+      # Messages locally queued.
+      #
+      # If no Receiver is found within the time out period, then a MessageError
+      # is raised.
       #
       # ==== Arguments
       #
-      # * timeout - time to wait for a +Receiver+ before timing out
+      # * +timeout+ - the duration
       #
       # ==== Examples
       #
-      #   recv = session.next_receiver # wait forever for the next +Receiver+
-      #   # execute a block on the next receiver
-      #   session.next_receiver do |recv|
-      #     msg = recv.get
-      #     puts "Received message: #{msg.content}"
+      #   loop do
+      #
+      #     begin
+      #       # wait a maximum of one minute for the next receiver to be ready
+      #       recv = session.next_receiver Qpid::Messaging::Duration::MINUTE
+      #
+      #       # get and dispatch the message
+      #       msg = recv.get
+      #       dispatch_message msg
+      #
+      #     rescue
+      #       puts "No receivers were returned"
+      #     end
+      #
       #   end
       def next_receiver(timeout = Qpid::Messaging::Duration::FOREVER, &block)
         receiver_impl = @session_impl.nextReceiver(timeout.duration_impl)
@@ -222,10 +237,6 @@ module Qpid
       end
 
       # Returns true if there were exceptions on this session.
-      #
-      # ==== Examples
-      #
-      #   puts "There were session errors." if @session.errors?
       def errors?; @session_impl.hasError; end
 
       # If the +Session+ has been rendered invalid due to some exception,
@@ -235,6 +246,7 @@ module Qpid
       #
       # ==== Examples
       #
+      #   # show any errors that occurred during the Session
       #   if @session.errors?
       #     begin
       #       @session.errors