adhearsion 0.8.4 → 0.8.5

data/lib/adhearsion/initializer/xmpp.rb

@@ -0,0 +1,42 @@
+require 'adhearsion/xmpp/connection.rb'
+
+module Adhearsion
+  class Initializer
+    class XMPPInitializer
+
+      cattr_accessor :config, :jid, :password, :server, :port
+      class << self
+
+        def start
+          require_dependencies
+          XMPP::Connection.extend Blather::DSL
+          ahn_config    = Adhearsion::AHN_CONFIG
+          self.config   = ahn_config.xmpp
+          self.jid      = config.jid
+          self.password = config.password
+          self.server   = config.server
+          self.port     = config.port
+
+          XMPP::Connection.start(jid, password, server, port)
+        end
+
+        def stop
+          XMPP::Connection.stop
+        end
+
+        private
+
+        def require_dependencies
+          begin
+            require 'blather/client/client'
+            require 'blather/client/dsl'
+          rescue LoadError
+            ahn_log.fatal "XMPP support requires the \"blather\" gem."
+            # Silence the abort so we don't get an ugly backtrace
+            abort ""
+          end
+        end
+      end
+    end
+  end
+end

data/lib/adhearsion/version.rb

@@ -2,8 +2,32 @@ module Adhearsion #:nodoc:
   module VERSION #:nodoc:
     MAJOR = 0 unless defined? MAJOR
     MINOR = 8 unless defined? MINOR
-    TINY  = 4 unless defined? TINY
+    TINY  = 5 unless defined? TINY
 
     STRING = [MAJOR, MINOR, TINY].join('.') unless defined? STRING
   end
-end
+
+  class PkgVersion
+    include Comparable
+
+    attr_reader :major, :minor, :revision
+
+    def initialize(version="")
+      @major, @minor, @revision = version.split(".").map(&:to_i)
+    end
+
+    def <=>(other)
+      return @major <=> other.major if ((@major <=> other.major) != 0)
+      return @minor <=> other.minor if ((@minor <=> other.minor) != 0)
+      return @revision <=> other.revision if ((@revision <=> other.revision) != 0)
+    end
+
+    def self.sort
+      self.sort!{|a,b| a <=> b}
+    end
+
+    def to_s
+      @major.to_s + "." + @minor.to_s + "." + @revision.to_s
+    end
+  end
+end

data/lib/adhearsion/voip/asterisk/agi_server.rb

@@ -12,7 +12,7 @@ module Adhearsion
             end
 
             def disconnecting(port)
-              @call.deliver_message :cancel
+              @call.deliver_message :cancel if !@call.nil?
               super(port)
             end
 
@@ -34,6 +34,7 @@ module Adhearsion
       	      DialPlan::Manager.handle call
     	      rescue Hangup
     	        ahn_log.agi "HANGUP event for call with uniqueid #{call.variables[:uniqueid].inspect} and channel #{call.variables[:channel].inspect}"
+              Events.trigger_immediately([:asterisk, :after_call], call)
     	        call.hangup!
             rescue DialPlan::Manager::NoContextError => e
               ahn_log.agi e.message

data/lib/adhearsion/voip/asterisk/commands.rb

@@ -43,25 +43,32 @@ module Adhearsion
         } unless defined? DYNAMIC_FEATURE_EXTENSIONS
 
         # Utility method to write to pbx.
+        # @param [String] message raw message
         def write(message)
-          to_pbx.print(message)
+          to_pbx.print(message + "\n")
         end
 
         # Utility method to read from pbx. Hangup if nil.
         def read
           returning from_pbx.gets do |message|
+            ahn_log.agi.debug "<<< #{message}"
+            # AGI has many conditions that might indicate a hangup
             raise Hangup if message.nil?
             raise Hangup if message.match(/^HANGUP\n?$/i)
+            raise Hangup if message.match(/^HANGUP\s?\d{3}/i)
             raise Hangup if message.match(/^511 Command Not Permitted on a dead channel/i)
-            ahn_log.agi.debug "<<< #{message}"
           end
         end
 
-        # This method is the underlying method executed by nearly all the command methods in this module.
-        # It is used to send the plaintext commands in the proper AGI format over TCP/IP back to an Asterisk server via the
+        # The underlying method executed by nearly all the command methods in this module.
+        # Used to send the plaintext commands in the proper AGI format over TCP/IP back to an Asterisk server via the
         # FAGI protocol.
+        #
         # It is not recommended that you call this method directly unless you plan to write a new command method
-        # in which case use this method you to communicate directly with an Asterisk server via the FAGI protocol.
+        # in which case use this to communicate directly with an Asterisk server via the FAGI protocol.
+        #
+        # @param [String] message
+        #
         # @see http://www.voip-info.org/wiki/view/Asterisk+FastAGI More information about FAGI
         def raw_response(message = nil)
           raise ArgumentError.new("illegal NUL in message #{message.inspect}") if message =~ /\0/
@@ -83,14 +90,13 @@ module Adhearsion
           end
         end
 
-        # The answer command must be called first before any other commands can be issued.
-        # In typical adhearsion applications the answer command is called by default as soon
-        # as a call is transfered to a valid context in dialplan.rb.
-        # If you do not want your adhearsion application to automatically issue an answer command,
+        # This must be called first before any other commands can be issued.
+        # In typical Adhearsion applications this is called by default as soon as a call is
+        # transfered to a valid context in dialplan.rb.
+        # If you do not want your Adhearsion application to automatically issue an answer command,
         # then you must edit your startup.rb file and configure this setting.
-        # Keep in mind that you should not need to issue another answer command after
-        # an answer command has already been issued either explicitly by your code or implicitly
-        # by the standard adhearsion configuration.
+        # Keep in mind that you should not need to issue another answer command after one has already
+        # been issued either explicitly by your code or implicitly by the standard adhearsion configuration.
         def answer
           response "ANSWER"
           true
@@ -100,10 +106,10 @@ module Adhearsion
         # which are typically run from extensions.conf.
         #
         # The most common commands are already made available through the FAGI interface provided
-        # by this code base.  For commands that do not fall into this category, then exec is what you
+        # by this code base. For commands that do not fall into this category, then exec is what you
         # should use.
         #
-        # For example, if there are specific asterisk modules you have loaded that will not
+        # For example, if there are specific asterisk modules you have loaded that will not be
         # available through the standard commands provided through FAGI - then you can used EXEC.
         #
         # @example Using execute in this way will add a header to an existing SIP call.
@@ -118,6 +124,12 @@ module Adhearsion
         end
 
         # Sends a message to the console via the verbose message system.
+        #
+        # @param [String] message
+        # @param [Integer] level
+        #
+        # @return the result of the command
+        #
         # @example Use this command to inform someone watching the Asterisk console
         # of actions happening within Adhearsion.
         #   verbose 'Processing call with Adhearsion' 3
@@ -141,7 +153,7 @@ module Adhearsion
         # numbers, Adhearsion assumes you're saying the number, not the digits. For example, play("100")
         # is pronounced as "one hundred" instead of "one zero zero".
         #
-        # Note: it's not necessary to supply a sound file extension; Asterisk will try to find a sound
+        # Note: it is not necessary to supply a sound file extension; Asterisk will try to find a sound
         # file encoded using the current channel's codec, if one exists. If not, it will transcode from
         # the default codec (GSM). Asterisk stores its sound files in /var/lib/asterisk/sounds.
         #
@@ -176,7 +188,17 @@ module Adhearsion
         #
         def record(*args)
           options = args.last.kind_of?(Hash) ? args.pop : {}
-          filename = args.shift || "/tmp/recording_%d.gsm"
+          filename = args.shift || "/tmp/recording_%d"
+
+          if filename.index("%d")
+            if @call.variables.has_key?(:recording_counter)
+              @call.variables[:recording_counter] += 1
+            else
+              @call.variables[:recording_counter]  = 0
+            end
+            filename = filename % @call.variables[:recording_counter]
+          end
+
           if (!options.has_key?(:format))
             format = filename.slice!(/\.[^\.]+$/)
             if (format.nil?)
@@ -187,32 +209,36 @@ module Adhearsion
           else
             format = options.delete(:format)
           end
-          silence     = options.delete(:silence) || 0
+
+          # maxduration must be in milliseconds when using RECORD FILE
           maxduration = options.delete(:maxduration) || -1
+          maxduration = maxduration * 1000 if maxduration > 0
+
           escapedigits = options.delete(:escapedigits) || "#"
+          silence     = options.delete(:silence) || 0
 
           if (silence > 0)
-            response("RECORD FILE", filename, format, escapedigits, maxduration,0, "BEEP", "s=#{silence}")
+            response("RECORD FILE", filename, format, escapedigits, maxduration, 0, "BEEP", "s=#{silence}")
           else
             response("RECORD FILE", filename, format, escapedigits, maxduration, 0, "BEEP")
           end
 
           # If the user hangs up before the recording is entered, -1 is returned and RECORDED_FILE
           # will not contain the name of the file, even though it IS in fact recorded.
-          filename.index("%d") ? get_variable('RECORDED_FILE') : filename + "." + format
+          filename + "." + format
         end
 
         # Simulates pressing the specified digits over the current channel. Can be used to
         # traverse a phone menu.
         def dtmf(digits)
-      		execute "SendDTMF", digits.to_s
-      	end
+          execute "SendDTMF", digits.to_s
+        end
 
-      	# The with_next_message method...
-      	def with_next_message(&block)
-      	  raise LocalJumpError, "Must supply a block" unless block_given?
+        # The with_next_message method...
+        def with_next_message(&block)
+          raise LocalJumpError, "Must supply a block" unless block_given?
           block.call(next_message)
-    	end
+        end
 
         # This command should be used to advance to the next message in the Asterisk Comedian Voicemail application
         def next_message
@@ -224,7 +250,7 @@ module Adhearsion
           not @call.inbox.empty?
         end
 
-        # Menu creates an interactive menu for the caller.
+        # Creates an interactive menu for the caller.
         #
         # The following documentation was derived from a post on Jay Phillips' blog (see below).
         #
@@ -389,7 +415,7 @@ module Adhearsion
           end
         end
 
-        # This method is used to receive keypad input from the user. Digits are collected
+        # Used to receive keypad input from the user. Digits are collected
         # via DTMF (keypad) input until one of three things happens:
         #
         #  1. The number of digits you specify as the first argument is collected
@@ -416,8 +442,8 @@ module Adhearsion
       	# causes the timer to reset. This is a much more user-friendly approach than an
         # absolute timeout.
       	#
-      	# Note that when you don't specify a digit limit, the :accept_key becomes "#"
-      	# because there'd be no other way to end the collection of digits. You can
+        # Note that when the digit limit is not specified the :accept_key becomes "#".
+        # Otherwise there would be no way to end the collection of digits. You can
       	# obviously override this by passing in a new key with :accept_key.
         def input(*args)
           options = args.last.kind_of?(Hash) ? args.pop : {}
@@ -469,7 +495,12 @@ module Adhearsion
         # you should assign the important ones to an instance variable first before calling this method.
         def jump_to(context, overrides={})
           context = lookup_context_with_name(context) if context.kind_of?(Symbol) || (context.kind_of?(String) && context =~ /^[\w_]+$/)
-          raise Adhearsion::VoIP::DSL::Dialplan::ContextNotFoundException unless context.kind_of?(Adhearsion::DialPlan::DialplanContextProc)
+
+          # JRuby has a bug that prevents us from correctly determining the class name.
+          # See: http://jira.codehaus.org/browse/JRUBY-5026
+          if !(context.kind_of?(Adhearsion::DialPlan::DialplanContextProc) || context.kind_of?(Proc))
+            raise Adhearsion::VoIP::DSL::Dialplan::ContextNotFoundException
+          end
 
           if overrides.any?
             overrides = overrides.symbolize_keys
@@ -485,9 +516,13 @@ module Adhearsion
           raise Adhearsion::VoIP::DSL::Dialplan::ControlPassingException.new(context)
         end
 
-      	# The queue method puts a call into a call queue to be answered by an agent registered with that queue.
-      	# The queue method takes a queue_name as an argument to place the caller in the appropriate queue.
+      	# Place a call in a queue to be answered by a registered agent. You must then call join!()
+      	#
+      	# @param [String] queue_name the queue name to place the caller in
+      	# @return [Adhearsion::VoIP::Asterisk::Commands::QueueProxy] a queue proxy object
+        #
         # @see http://www.voip-info.org/wiki-Asterisk+cmd+Queue Full information on the Asterisk Queue
+        # @see Adhearsion::VoIP::Asterisk::Commands::QueueProxy#join! join!() for further details
       	def queue(queue_name)
       	  queue_name = queue_name.to_s
 
@@ -503,19 +538,17 @@ module Adhearsion
       	  end
     	  end
 
-      	# Returns the status of the last dial(). Possible dial
-        # statuses include :answer, :busy, :no_answer, :cancelled,
-        # :congested, and :channel_unavailable. If :cancel is
-      	# returned, the caller hung up before the callee picked
-      	# up. If :congestion is returned, the dialed extension
-      	# probably doesn't exist. If :channel_unavailable, the callee
-      	# phone may not be registered.
+      	# Get the status of the last dial(). Possible dial statuses include :answer,
+        # :busy, :no_answer, :cancelled, :congested, and :channel_unavailable.
+        # If :cancel is returned, the caller hung up before the callee picked up.
+        # If :congestion is returned, the dialed extension probably doesn't exist.
+        # If :channel_unavailable, the callee phone may not be registered.
       	def last_dial_status
       	  DIAL_STATUSES[get_dial_status]
       	end
 
-        # Returns true if your last call to dial() finished with the ANSWER state, as reported
-        # by Asterisk. Returns false otherwise
+        # @return [Boolean] true if your last call to dial() finished with the ANSWER state,
+        # as reported by Asterisk. false otherwise
         def last_dial_successful?
           last_dial_status == :answered
         end
@@ -531,7 +564,7 @@ module Adhearsion
           execute SpeechEngines.send(engine, text)
         end
 
-        # This method is a high-level way of enabling features you create/uncomment from features.conf.
+        # A high-level way of enabling features you create/uncomment from features.conf.
         #
         # Certain Symbol features you enable (as defined in DYNAMIC_FEATURE_EXTENSIONS) have optional
         # arguments that you can also specify here. The usage examples show how to do this.
@@ -560,6 +593,8 @@ module Adhearsion
 
         # Disables a feature name specified in features.conf. If you're disabling it, it was probably
         # set by enable_feature().
+        #
+        # @param [String] feature_name
         def disable_feature(feature_name)
           enabled_features_variable = variable 'DYNAMIC_FEATURES'
           enabled_features = enabled_features_variable.split('#')
@@ -569,17 +604,25 @@ module Adhearsion
           end
         end
 
-        # Used to join a particular conference with the MeetMe application. To
-        # use MeetMe, be sure you have a proper timing device configured on your
-        # Asterisk box. MeetMe is Asterisk's built-in conferencing program.
+        # Used to join a particular conference with the MeetMe application. To use MeetMe, be sure you
+        # have a proper timing device configured on your Asterisk box. MeetMe is Asterisk's built-in
+        # conferencing program.
+        #
+        # @param [String] conference_id
+        # @param [Hash] options
+        #
         # @see http://www.voip-info.org/wiki-Asterisk+cmd+MeetMe Asterisk Meetme Application Information
         def join(conference_id, options={})
           conference_id = conference_id.to_s.scan(/\w/).join
           command_flags = options[:options].to_s # This is a passthrough string straight to Asterisk
           pin = options[:pin]
           raise ArgumentError, "A conference PIN number must be numerical!" if pin && pin.to_s !~ /^\d+$/
+
+          # To disable dynamic conference creation set :use_static_conf => true
+          use_static_conf = options.has_key?(:use_static_conf) ? options[:use_static_conf] : false
+
           # The 'd' option of MeetMe creates conferences dynamically.
-          command_flags += 'd' unless command_flags.include? 'd'
+          command_flags += 'd' unless (command_flags.include?('d') or use_static_conf)
 
           execute "MeetMe", conference_id, command_flags, options[:pin]
         end
@@ -587,7 +630,10 @@ module Adhearsion
         # Issue this command to access a channel variable that exists in the asterisk dialplan (i.e. extensions.conf)
         # Use get_variable to pass information from other modules or high level configurations from the asterisk dialplan
         # to the adhearsion dialplan.
-	# @see: http://www.voip-info.org/wiki/view/get+variable Asterisk Get Variable
+        #
+        # @param [String] variable_name
+        #
+        # @see: http://www.voip-info.org/wiki/view/get+variable Asterisk Get Variable
       	def get_variable(variable_name)
       	  result = response("GET VARIABLE", variable_name)
       	  case result
@@ -598,17 +644,22 @@ module Adhearsion
     	    end
     	  end
 
-    	  # Use set_variable to pass information back to the asterisk dial plan.
-    	  # Keep in mind that the variables are not global variables.  These variables only exist for the channel
+    	  # Pass information back to the asterisk dial plan.
+    	  #
+    	  # Keep in mind that the variables are not global variables. These variables only exist for the channel
     	  # related to the call that is being serviced by the particular instance of your adhearsion application.
     	  # You will not be able to pass information back to the asterisk dialplan for other instances of your adhearsion
-    	  # application to share.  Once the channel is "hungup" then the variables are cleared and their information is gone.
+    	  # application to share. Once the channel is "hungup" then the variables are cleared and their information is gone.
+    	  #
+    	  # @param [String] variable_name
+    	  # @param [String] value
+    	  #
     	  # @see http://www.voip-info.org/wiki/view/set+variable Asterisk Set Variable
     	  def set_variable(variable_name, value)
     	    response("SET VARIABLE", variable_name, value) == "200 result=1"
   	    end
 
-    	  # The variable method allows you to either set or get a channel variable from Asterisk
+    	  # Allows you to either set or get a channel variable from Asterisk.
     	  # The method takes a hash key/value pair if you would like to set a variable
     	  # Or a single string with the variable to get from Asterisk
     	  def variable(*args)
@@ -627,10 +678,12 @@ module Adhearsion
     	    end
   	    end
 
-    	  # Use the voicemail method to send a caller to a voicemail box to leave a message.
-    	  # @see http://www.voip-info.org/tiki-index.php?page=Asterisk+cmd+VoiceMail Asterisk Voicemail
+    	  # Send a caller to a voicemail box to leave a message.
+    	  #
     	  # The method takes the mailbox_number of the user to leave a message for and a
     	  # greeting_option that will determine which message gets played to the caller.
+    	  #
+    	  # @see http://www.voip-info.org/tiki-index.php?page=Asterisk+cmd+VoiceMail Asterisk Voicemail
         def voicemail(*args)
           options_hash    = args.last.kind_of?(Hash) ? args.pop : {}
           mailbox_number  = args.shift
@@ -665,6 +718,9 @@ module Adhearsion
 
         # The voicemail_main method puts a caller into the voicemail system to fetch their voicemail
         # or set options for their voicemail box.
+        #
+        # @param [Hash] options
+        #
         # @see http://www.voip-info.org/wiki-Asterisk+cmd+VoiceMailMain Asterisk VoiceMailMain Command
         def voicemail_main(options={})
           mailbox, context, folder = options.values_at :mailbox, :context, :folder
@@ -702,15 +758,15 @@ module Adhearsion
           voicemail_main
         end
 
-        # Use this command to dial an extension or "phone number" in asterisk.
-        # This command maps to the Asterisk DIAL command in the asterisk dialplan.
+        # Dial an extension or "phone number" in asterisk.
+        # Maps to the Asterisk DIAL command in the asterisk dialplan.
         #
-        # The first parameter, number, must be a string that represents the extension or "number" that asterisk should dial.
+        # @param [String] number represents the extension or "number" that asterisk should dial.
         # Be careful to not just specify a number like 5001, 9095551001
         # You must specify a properly formatted string as Asterisk would expect to use in order to understand
         # whether the call should be dialed using SIP, IAX, or some other means.
         #
-        # Options Parameter:
+        # @param [Hash] options
         #
         # +:caller_id+ - the caller id number to be used when the call is placed.  It is advised you properly adhere to the
         # policy of VoIP termination providers with respect to caller id values.
@@ -727,7 +783,7 @@ module Adhearsion
         # for a complete list of these options and their usage please check the link below.
         #
         # +:confirm+ - ?
-	#
+        #
         # @example Make a call to the PSTN using my SIP provider for VoIP termination
         #   dial("SIP/19095551001@my.sip.voip.terminator.us")
         #
@@ -738,7 +794,7 @@ module Adhearsion
         # @example Make a call using the IAX provider to the PSTN
         #   dial("IAX2/my.id@voipjet/19095551234", :name=>"John Doe", :caller_id=>"9095551234")
         #
-	# @see http://www.voip-info.org/wiki-Asterisk+cmd+Dial Asterisk Dial Command
+        # @see http://www.voip-info.org/wiki-Asterisk+cmd+Dial Asterisk Dial Command
         def dial(number, options={})
           *recognized_options = :caller_id, :name, :for, :options, :confirm
 
@@ -774,15 +830,19 @@ module Adhearsion
 
 
       	# Speaks the digits given as an argument. For example, "123" is spoken as "one two three".
+      	#
+      	# @param [String] digits
       	def say_digits(digits)
       	  execute "saydigits", validate_digits(digits)
       	end
 
-      	# Returns the number of seconds the given block takes to execute as a Float. This
+      	# Get the number of seconds the given block takes to execute. This
       	# is particularly useful in dialplans for tracking billable time. Note that
       	# if the call is hung up during the block, you will need to rescue the
       	# exception if you have some mission-critical logic after it with which
       	# you're recording this return-value.
+      	#
+      	# @return [Float] number of seconds taken for block to execute
         def duration_of
           start_time = Time.now
           yield
@@ -790,8 +850,9 @@ module Adhearsion
         end
 
         #
-        # This will play a sequence of files, stopping the playback if a digit is pressed. If a digit is pressed, it will be
-        # returned as a String. If the files played with no keypad input, nil will be returned.
+        # Play a sequence of files, stopping the playback if a digit is pressed.
+        #
+        # @return [String, nil] digit pressed, or nil if none
         #
         def interruptible_play(*files)
           files.flatten.each do |file|
@@ -818,14 +879,14 @@ module Adhearsion
             interruptible_play(*files)
           end
 
-          # set_callier_id_number method allows setting of the callerid number of the call
+          # allows setting of the callerid number of the call
           def set_caller_id_number(caller_id)
             return unless caller_id
             raise ArgumentError, "Caller ID must be numerical" if caller_id.to_s !~ /^\d+$/
             response "SET CALLERID", caller_id
           end
 
-          # set_caller_id_name method allows the setting of the callerid name of the call
+          # allows the setting of the callerid name of the call
           def set_caller_id_name(caller_id_name)
             return unless caller_id_name
             variable "CALLERID(name)" => caller_id_name
@@ -972,7 +1033,7 @@ module Adhearsion
           end
 
           def error?(result)
-            result.to_s[/^#{response_prefix}(?:-\d+|0)/]
+            result.to_s[/^#{response_prefix}(?:-\d+)/]
           end
 
           # timeout with pressed digits:    200 result=<digits> (timeout)
@@ -1046,8 +1107,9 @@ module Adhearsion
               @name, @environment = name, environment
             end
 
-            # Makes the current channel join the queue. Below are explanations of the recognized Hash-key
-            # arguments supported by this method.
+            # Makes the current channel join the queue.
+            #
+            # @param [Hash] options
             #
             #   :timeout        - The number of seconds to wait for an agent to answer
             #   :play           - Can be :ringing or :music.
@@ -1055,24 +1117,37 @@ module Adhearsion
             #   :allow_transfer - Can be :caller, :agent, or :everyone. Allow someone to transfer the call.
             #   :allow_hangup   - Can be :caller, :agent, or :everyone. Allow someone to hangup with the * key.
             #
-            # Usage examples:
-            #
-            #  - queue('sales').join!
-            #  - queue('sales').join! :timeout => 1.minute
-            #  - queue('sales').join! :play => :music
-            #  - queue('sales').join! :play => :ringing
-            #  - queue('sales').join! :announce => "custom/special-queue-announcement"
-            #  - queue('sales').join! :allow_transfer => :caller
-            #  - queue('sales').join! :allow_transfer => :agent
-            #  - queue('sales').join! :allow_hangup   => :caller
-            #  - queue('sales').join! :allow_hangup   => :agent
-            #  - queue('sales').join! :allow_hangup   => :everyone
-            #  - queue('sales').join! :allow_transfer => :agent, :timeout => 30.seconds,
+            #  @example
+            #    queue('sales').join!
+            #  @example
+            #    queue('sales').join! :timeout => 1.minute
+            #  @example
+            #    queue('sales').join! :play => :music
+            #  @example
+            #    queue('sales').join! :play => :ringing
+            #  @example
+            #    queue('sales').join! :announce => "custom/special-queue-announcement"
+            #  @example
+            #    queue('sales').join! :allow_transfer => :caller
+            #  @example
+            #    queue('sales').join! :allow_transfer => :agent
+            #  @example
+            #    queue('sales').join! :allow_hangup   => :caller
+            #  @example
+            #    queue('sales').join! :allow_hangup   => :agent
+            #  @example
+            #    queue('sales').join! :allow_hangup   => :everyone
+            #  @example
+            #    queue('sales').join! :allow_transfer => :agent, :timeout => 30.seconds,
             def join!(options={})
               environment.execute("queue", name, *self.class.format_join_hash_key_arguments(options))
           	  normalize_queue_status_variable environment.variable("QUEUESTATUS")
             end
 
+            # Get the agents associated with a queue
+            #
+            # @param [Hash] options
+            # @return [QueueAgentsListProxy]
             def agents(options={})
               cached = options.has_key?(:cache) ? options.delete(:cache) : true
               raise ArgumentError, "Unrecognized arguments to agents(): #{options.inspect}" if options.keys.any?
@@ -1083,19 +1158,28 @@ module Adhearsion
               end
             end
 
+            # Check how many channels are waiting in the queue
+            # @return [Integer]
+            # @raise QueueDoesNotExistError
             def waiting_count
               raise QueueDoesNotExistError.new(name) unless exists?
               environment.variable("QUEUE_WAITING_COUNT(#{name})").to_i
             end
 
+            # Check whether the waiting count is zero
+            # @return [Boolean]
             def empty?
               waiting_count == 0
             end
 
+            # Check whether any calls are waiting in the queue
+            # @return [Boolean]
             def any?
               waiting_count > 0
             end
 
+            # Check whether a queue exists/is defined in Asterisk
+            # @return [Boolean]
             def exists?
               environment.execute('RemoveQueueMember', name, 'SIP/AdhearsionQueueExistenceCheck')
               environment.variable("RQMSTATUS") != 'NOSUCHQUEUE'
@@ -1103,7 +1187,24 @@ module Adhearsion
 
             private
 
+            # Ensure the queue exists by interpreting the QUEUESTATUS variable
+            #
+            # According to http://www.voip-info.org/wiki/view/Asterisk+cmd+Queue
+            # possible values are:
+            # TIMEOUT (:timeout
+            # FULL (:full)
+            # JOINEMPTY (:joinempty)
+            # LEAVEEMPTY (:leaveempty)
+            # JOINUNAVAIL (:joinunavail)
+            # LEAVEUNAVAIL (:leaveunavail)
+            #
+            # If Adhearsion cannot determine the status then :unknown will be returned.
+            #
+            # @param [String] QUEUESTATUS variable from Asterisk
+            # @return [Symbol] Symbolized version of QUEUESTATUS
+            # @raise QueueDoesNotExistError
             def normalize_queue_status_variable(variable)
+              variable = "UNKNOWN" if variable.nil?
               returning variable.downcase.to_sym do |queue_status|
                 raise QueueDoesNotExistError.new(name) if queue_status == :unknown
               end
@@ -1129,9 +1230,9 @@ module Adhearsion
               alias size count
               alias length count
 
-              # Supported Hash-key arguments are :penalty and :name. The :name value will be viewable in
-              # the queue_log. The :penalty is the penalty assigned to this agent for answering calls on
-              # this queue
+              # @param [Hash] args
+              # :name value will be viewable in the queue_log
+              # :penalty is the penalty assigned to this agent for answering calls on this queue
               def new(*args)
 
                 options   = args.last.kind_of?(Hash) ? args.pop : {}
@@ -1309,7 +1410,7 @@ module Adhearsion
 
             end
 
-            class QueueDoesNotExistError < Exception
+            class QueueDoesNotExistError < StandardError
               def initialize(queue_name)
                 super "Queue #{queue_name} does not exist!"
               end
@@ -1325,7 +1426,7 @@ module Adhearsion
 
           module SpeechEngines
 
-            class InvalidSpeechEngine < Exception; end
+            class InvalidSpeechEngine < StandardError; end
 
             class << self
               def cepstral(text)