blather 0.4.16 → 0.5.0

data/lib/blather/stanza/disco/disco_items.rb

@@ -121,7 +121,6 @@ class Stanza
         write_attr :name, name
       end
 
-
       # Compare two DiscoItems::Item objects by name, type and category
       # @param [DiscoItems::Item] o the Identity object to compare against
       # @return [true, false]

data/lib/blather/stanza/iq.rb

@@ -53,6 +53,7 @@ class Stanza
   #
   # @handler :iq
   class Iq < Stanza
+    # @private
     VALID_TYPES = [:get, :set, :result, :error].freeze
 
     register :iq
@@ -124,10 +125,15 @@ class Stanza
       super
     end
 
-    # Overrides the parent method to ensure the reply is of type :result
+    # Overrides the parent method to ensure the reply is of type :result and that
+    # all children are removed.
+    #
+    # @param [Hash] opts options to pass to reply!
+    # @option opts [Boolean] :remove_children Wether or not to remove child nodes when replying
     #
     # @return [self]
-    def reply!
+    def reply!(opts = {})
+      opts = {:remove_children => true}.merge opts
       super
       self.type = :result
       self

data/lib/blather/stanza/iq/command.rb

@@ -11,8 +11,11 @@ class Iq
   #
   # @handler :command
   class Command < Iq
+    # @private
     VALID_ACTIONS = [:cancel, :execute, :complete, :next, :prev].freeze
+    # @private
     VALID_STATUS = [:executing, :completed, :canceled].freeze
+    # @private
     VALID_NOTE_TYPES = [:info, :warn, :error].freeze
 
     register :command, :command, 'http://jabber.org/protocol/commands'
@@ -44,8 +47,11 @@ class Iq
 
     # Overrides the parent method to ensure the reply has no action
     #
+    # @param [Hash] opts options to pass to reply!
+    # @option opts [Boolean] :remove_children Wether or not to remove child nodes when replying
+    #
     # @return [self]
-    def reply!
+    def reply!(opts = {})
       super
       self.action = nil
       self
@@ -215,17 +221,26 @@ class Iq
 
     # Get the command's allowed actions
     #
-    # @return [[Symbol]]
+    # @return [Array<Symbol>]
     def allowed_actions
       ([:execute] + actions.children.map { |action| action.name.to_sym }).uniq
     end
 
+    # Get the primary allowed action
+    #
+    # @return [Symbol]
     def primary_allowed_action
       (actions[:execute] || :execute).to_sym
     end
 
+    # Set the primary allowed action
+    #
+    # This must be one of :prev, :next, :complete or :execute
+    #
+    # @param [#to_sym] a the primary allowed action
     def primary_allowed_action=(a)
-      if a && ![:prev, :next, :complete, :execute].include?(a.to_sym)
+      a = a.to_sym
+      if a && ![:prev, :next, :complete, :execute].include?(a)
         raise ArgumentError, "Invalid Action (#{a}), use: #{[:prev, :next, :complete, :execute]*' '}"
       end
       actions[:execute] = a

data/lib/blather/stanza/iq/ibb.rb

@@ -1,8 +1,6 @@
 module Blather
 class Stanza
 class Iq
-  NS_IBB = 'http://jabber.org/protocol/ibb'
-
   # # In-Band Bytestreams Stanza
   #
   # [XEP-0047: In-Band Bytestreams](http://xmpp.org/extensions/xep-0047.html)
@@ -11,6 +9,8 @@ class Iq
   # @handler :ibb_data
   # @handler :ibb_close
   class Ibb < Iq
+    # @private
+    NS_IBB = 'http://jabber.org/protocol/ibb'
 
     # Overrides the parent method to remove open, close and data nodes
     #
@@ -23,6 +23,7 @@ class Iq
       reply
     end
 
+    # An Open stanza to
     class Open < Ibb
       register :ibb_open, :open, NS_IBB
 
@@ -42,6 +43,7 @@ class Iq
 
     end
 
+    # A Data stanza
     class Data < Ibb
       register :ibb_data, :data, NS_IBB
 
@@ -60,6 +62,7 @@ class Iq
       end
     end
 
+    # A Close stanza
     class Close < Ibb
       register :ibb_close, :close, NS_IBB
 
@@ -80,4 +83,4 @@ class Iq
   end
 end
 end
-end
+end

data/lib/blather/stanza/iq/s5b.rb

@@ -1,14 +1,15 @@
 module Blather
 class Stanza
 class Iq
-  NS_S5B = 'http://jabber.org/protocol/bytestreams'
-
   # # SOCKS5 Bytestreams Stanza
   #
   # [XEP-0065: SOCKS5 Bytestreams](http://xmpp.org/extensions/xep-0065.html)
   #
   # @handler :s5b_open
   class S5b < Query
+    # @private
+    NS_S5B = 'http://jabber.org/protocol/bytestreams'
+
     register :s5b_open, :query, NS_S5B
 
     # Overrides the parent method to remove query node
@@ -64,6 +65,7 @@ class Iq
       end
     end
 
+    # StreamHost Stanza
     class StreamHost < XMPPNode
       register 'streamhost', NS_S5B
 
@@ -152,6 +154,7 @@ class Iq
       end
     end
 
+    # Stream host used stanza
     class StreamHostUsed < XMPPNode
       register 'streamhost-used', NS_S5B
 
@@ -202,4 +205,4 @@ class Iq
   end
 end
 end
-end
+end

data/lib/blather/stanza/iq/si.rb

@@ -33,6 +33,7 @@ class Iq
   #
   # @handler :file_transfer
   class Si < Iq
+    # @private
     NS_SI = 'http://jabber.org/protocol/si'
     register :file_transfer, :si, NS_SI
 
@@ -80,6 +81,7 @@ class Iq
       reply
     end
 
+    # Si stanza fragment
     class Si < XMPPNode
       # Create a new Si::Si object
       #
@@ -166,6 +168,7 @@ class Iq
         Feature.find_or_create self
       end
 
+      # Feature stanza fragment
       class Feature < XMPPNode
         register :feature, 'http://jabber.org/protocol/feature-neg'
 
@@ -206,6 +209,7 @@ class Iq
         end
       end
 
+      # File stanza fragment
       class File < XMPPNode
         register :file, 'http://jabber.org/protocol/si/profile/file-transfer'
 
@@ -330,6 +334,7 @@ class Iq
         end
       end
 
+      # Range stanza fragment
       class Range < XMPPNode
         register :range, 'http://jabber.org/protocol/si/profile/file-transfer'
 
@@ -407,4 +412,4 @@ class Iq
   end
 end
 end
-end
+end

data/lib/blather/stanza/iq/vcard.rb

@@ -69,8 +69,10 @@ class Iq
       Vcard.find_or_create self
     end
 
+    # Vcard stanza fragment
     class Vcard < XMPPNode
 
+      # @private
       VCARD_NS = 'vcard-temp'
 
       # Create a new Vcard::Vcard object
@@ -144,4 +146,4 @@ class Iq
   end
 end
 end
-end
+end

data/lib/blather/stanza/message.rb

@@ -157,12 +157,17 @@ class Stanza
   #
   # @handler :message
   class Message < Stanza
+    # @private
     VALID_TYPES = [:chat, :error, :groupchat, :headline, :normal].freeze
 
+    # @private
     VALID_CHAT_STATES = [:active, :composing, :gone, :inactive, :paused].freeze
+    # @private
     CHAT_STATE_NS = 'http://jabber.org/protocol/chatstates'.freeze
 
+    # @private
     HTML_NS = 'http://jabber.org/protocol/xhtml-im'.freeze
+    # @private
     HTML_BODY_NS = 'http://www.w3.org/1999/xhtml'.freeze
 
     register :message

data/lib/blather/stanza/presence.rb

@@ -70,6 +70,7 @@ class Stanza
   #
   # @handler :presence
   class Presence < Stanza
+    # @private
     VALID_TYPES = [ :unavailable,
                     :subscribe,
                     :subscribed,

data/lib/blather/stanza/presence/c.rb

@@ -13,6 +13,7 @@ class Presence
   class C < Presence
     register :c, :c, 'http://jabber.org/protocol/caps'
 
+    # @private
     VALID_HASH_TYPES = %w[md2 md5 sha-1 sha-224 sha-256 sha-384 sha-512].freeze
 
     def self.new(node = nil, ver = nil, hash = 'sha-1')

data/lib/blather/stanza/presence/status.rb

@@ -75,6 +75,7 @@ class Presence
   #
   # @handler :status
   class Status < Presence
+    # @private
     VALID_STATES = [:away, :chat, :dnd, :xa].freeze
 
     include Comparable

data/lib/blather/stanza/pubsub/event.rb

@@ -11,6 +11,7 @@ class PubSub
   #
   # @handler :pubsub_event
   class Event < Message
+    # @private
     SHIM_NS = 'http://jabber.org/protocol/shim'.freeze
 
     register :pubsub_event, :event, 'http://jabber.org/protocol/pubsub#event'
@@ -130,10 +131,7 @@ class PubSub
     def subscription_node
       event_node.find_first('//ns:subscription', :ns => self.class.registered_ns)
     end
-
-    def subscription
-      subscription_node
-    end
+    alias_method :subscription, :subscription_node
   end  # Event
 
 end  # PubSub

data/lib/blather/stanza/pubsub/subscription.rb

@@ -8,6 +8,7 @@ class PubSub
   #
   # @handler :pubsub_subscription
   class Subscription < PubSub
+    # @private
     VALID_TYPES = [:none, :pending, :subscribed, :unconfigured]
 
     register :pubsub_subscription, :subscription, self.registered_ns

data/lib/blather/stanza/x.rb

@@ -10,6 +10,7 @@ class Stanza
   class X < XMPPNode
     register :x, 'jabber:x:data'
 
+    # @private
     VALID_TYPES = [:cancel, :form, :result, :submit].freeze
 
     # Create a new X node
@@ -33,6 +34,10 @@ class Stanza
       new_node
     end
 
+    # Find the X node on the parent or create a new one
+    #
+    # @param [Blather::Stanza] parent the parent node to search under
+    # @return [Blather::Stanza::X]
     def self.find_or_create(parent)
       if found_x = parent.find_first('//ns:x', :ns => self.registered_ns)
         x = self.new found_x
@@ -149,8 +154,10 @@ class Stanza
       end
     end
 
+    # Field stanza fragment
     class Field < XMPPNode
       register :field, 'jabber:x:data'
+      # @private
       VALID_TYPES = [:boolean, :fixed, :hidden, :"jid-multi", :"jid-single", :"list-multi", :"list-single", :"text-multi", :"text-private", :"text-single"].freeze
 
       # Create a new X Field
@@ -335,6 +342,7 @@ class Stanza
         super o, *(fields + [:type, :var, :label, :desc, :required?, :value])
       end
 
+      # Option stanza fragment
       class Option < XMPPNode
         register :option, 'jabber:x:data'
         # Create a new X Field Option

data/lib/blather/stream.rb

@@ -48,8 +48,10 @@ module Blather
   #     client = Blather::Stream.start MyClient.new, "jid@domain/res", "pass"
   #     client.write "[pure xml over the wire]"
   class Stream < EventMachine::Connection
+    # Connection not found
     class NoConnection < RuntimeError; end
 
+    # @private
     STREAM_NS = 'http://etherx.jabber.org/streams'
     attr_accessor :password
     attr_reader :jid

data/lib/blather/stream/client.rb

@@ -1,6 +1,7 @@
 module Blather
 class Stream
 
+  # @private
   class Client < Stream
     LANG = 'en'
     VERSION = '1.0'

data/lib/blather/stream/component.rb

@@ -1,6 +1,7 @@
 module Blather
 class Stream
 
+  # @private
   class Component < Stream
     NAMESPACE = 'jabber:component:accept'
 

data/lib/blather/stream/features.rb

@@ -1,7 +1,8 @@
-module Blather # :nodoc:
-class Stream # :nodoc:
+module Blather
+class Stream
 
-  class Features # :nodoc:
+  # @private
+  class Features
     @@features = {}
     def self.register(ns)
       @@features[ns] = self

data/lib/blather/stream/features/resource.rb

@@ -1,7 +1,8 @@
-module Blather # :nodoc:
-class Stream # :nodoc:
+module Blather
+class Stream
 
-  class Resource < Features # :nodoc:
+  # @private
+  class Resource < Features
     BIND_NS = 'urn:ietf:params:xml:ns:xmpp-bind'.freeze
     register BIND_NS
 

data/lib/blather/stream/features/sasl.rb

@@ -1,7 +1,8 @@
-module Blather # :nodoc:
-class Stream # :nodoc:
+module Blather
+class Stream
 
-  class SASL < Features # :nodoc:
+  # @private
+  class SASL < Features
     class UnknownMechanism < BlatherError
       register :sasl_unknown_mechanism
     end
@@ -68,7 +69,7 @@ class Stream # :nodoc:
       when nil          then  fail!(SASLError.import(@node))
       else                    next!
       end
-      
+
       if method.is_a?(Module)
         extend method
         authenticate
@@ -170,13 +171,15 @@ class Stream # :nodoc:
       def h(s); Digest::MD5.hexdigest(s); end
     end #DigestMD5
 
-    module Plain # :nodoc:
+    # @private
+    module Plain
       def authenticate
         @stream.send auth_node('PLAIN', b64("#{@jid.stripped}\x00#{@jid.node}\x00#{@pass}"))
       end
     end #Plain
 
-    module Anonymous # :nodoc:
+    # @private
+    module Anonymous
       def authenticate
         @stream.send auth_node('ANONYMOUS')
       end