blather 0.4.7 → 0.4.8

data/lib/blather/roster.rb

@@ -1,20 +1,27 @@
 module Blather
 
-  ##
-  # Local Roster 
+  # Local Roster
   # Takes care of adding/removing JIDs through the stream
   class Roster
     include Enumerable
 
+    # Create a new roster
+    #
+    # @param [Blather::Stream] stream the stream the roster should use to
+    # update roster entries
+    # @param [Blather::Stanza::Roster] stanza a roster stanza used to preload
+    # the roster
+    # @return [Blather::Roster]
     def initialize(stream, stanza = nil)
       @stream = stream
       @items = {}
       stanza.items.each { |i| push i, false } if stanza
     end
 
-    ##
-    # Process any incoming stanzas adn either add or remove the
+    # Process any incoming stanzas and either adds or removes the
     # corresponding RosterItem
+    #
+    # @param [Blather::Stanza::Roster] stanza a roster stanza
     def process(stanza)
       stanza.items.each do |i|
         case i.subscription
@@ -24,18 +31,21 @@ module Blather
       end
     end
 
-    ##
     # Pushes a JID into the roster
-    # then returns self to allow for chaining
+    #
+    # @param [String, Blather::JID, #jid] elem a JID to add to the roster
+    # @return [self]
+    # @see #push
     def <<(elem)
       push elem
       self
     end
 
-    ##
-    # Push a JID into the roster
-    # Will send the new item to the server
-    # unless overridden by calling #push(elem, false)
+    # Push a JID into the roster and update the server
+    #
+    # @param [String, Blather::JID, #jid] elem a jid to add to the roster
+    # @param [true, false] send send the update over the wire
+    # @see Blather::JID
     def push(elem, send = true)
       jid = elem.respond_to?(:jid) ? elem.jid : JID.new(elem)
       @items[key(jid)] = node = RosterItem.new(elem)
@@ -44,35 +54,41 @@ module Blather
     end
     alias_method :add, :push
 
-    ##
-    # Remove a JID from the roster
-    # Sends a remove query stanza to the server
+    # Remove a JID from the roster and update the server
+    #
+    # @param [String, Blather::JID] jid the JID to remove from the roster
     def delete(jid)
       @items.delete key(jid)
-      @stream.write Stanza::Iq::Roster.new(:set, Stanza::Iq::Roster::RosterItem.new(jid, nil, :remove))
+      item = Stanza::Iq::Roster::RosterItem.new(jid, nil, :remove)
+      @stream.write Stanza::Iq::Roster.new(:set, item)
     end
     alias_method :remove, :delete
 
-    ##
     # Get a RosterItem by JID
+    #
+    # @param [String, Blather::JID] jid the jid of the item to return
+    # @return [Blather::RosterItem, nil] the associated RosterItem
     def [](jid)
       items[key(jid)]
     end
 
-    ##
     # Iterate over all RosterItems
+    #
+    # @yield [Blather::RosterItem] yields each RosterItem
     def each(&block)
       items.each &block
     end
 
-    ##
-    # Returns a duplicate of all RosterItems
+    # Get a duplicate of all RosterItems
+    #
+    # @return [Array<Blather::RosterItem>] a duplicate of all RosterItems
     def items
       @items.dup
     end
 
-    ##
     # A hash of items keyed by group
+    #
+    # @return [Hash<group => Array<RosterItem>>]
     def grouped
       self.inject(Hash.new{|h,k|h[k]=[]}) do |hash, item|
         item[1].groups.each { |group| hash[group] << item[1] }
@@ -81,13 +97,15 @@ module Blather
     end
 
   private
+    # Creates a stripped jid
     def self.key(jid)
       JID.new(jid).stripped.to_s
     end
 
+    # Instance method to wrap around the class method
     def key(jid)
       self.class.key(jid)
     end
-  end #Roster
+  end  # Roster
 
-end
+end  # Blather

data/lib/blather/roster_item.rb

@@ -1,10 +1,9 @@
 module Blather
 
-  ##
   # RosterItems hold internal representations of the user's roster
   # including each JID's status.
   class RosterItem
-    VALID_SUBSCRIPTION_TYPES = [:both, :from, :none, :remove, :to]
+    VALID_SUBSCRIPTION_TYPES = [:both, :from, :none, :remove, :to].freeze
 
     attr_reader :jid,
                 :ask,
@@ -18,8 +17,19 @@ module Blather
       super
     end
 
-    ##
-    # item:: can be a JID, String (a@b) or a Stanza
+    # Create a new RosterItem
+    #
+    # @overload initialize(jid)
+    #   Create a new RosterItem based on a JID
+    #   @param [Blather::JID] jid the JID object
+    # @overload initialize(jid)
+    #   Create a new RosterItem based on a JID string
+    #   @param [String] jid a JID string
+    # @overload initialize(node)
+    #   Create a new RosterItem based on a stanza
+    #   @param [Blather::Stanza::Iq::Roster::RosterItem] node a RosterItem
+    #   stanza
+    # @return [Blather::RosterItem] the new RosterItem
     def initialize(item)
       @statuses = []
       @groups = []
@@ -40,54 +50,66 @@ module Blather
       @groups = [nil] if @groups.empty?
     end
 
-    ##
     # Set the jid
+    #
+    # @param [String, Blather::JID] jid the new jid
+    # @see Blather::JID
     def jid=(jid)
       @jid = JID.new(jid).stripped
     end
 
-    ##
     # Set the subscription
     # Ensures it is one of VALID_SUBSCRIPTION_TYPES
+    #
+    # @param [#to_sym] sub the new subscription
     def subscription=(sub)
-      raise ArgumentError, "Invalid Type (#{sub}), use: #{VALID_SUBSCRIPTION_TYPES*' '}" if
-        sub && !VALID_SUBSCRIPTION_TYPES.include?(sub = sub.to_sym)
+      if sub && !VALID_SUBSCRIPTION_TYPES.include?(sub = sub.to_sym)
+        raise ArgumentError, "Invalid Type (#{sub}), use: #{VALID_SUBSCRIPTION_TYPES*' '}"
+      end
       @subscription = sub ? sub : :none
     end
 
-    ##
     # Get the current subscription
-    # returns:: :both, :from, :none, :remove, :to or :none
+    #
+    # @return [:both, :from, :none, :remove, :to]
     def subscription
       @subscription || :none
     end
 
-    ##
     # Set the ask value
-    # ask:: must only be nil or :subscribe
+    #
+    # @param [nil, :subscribe] ask the new ask
     def ask=(ask)
-      raise ArgumentError, "Invalid Type (#{ask}), can only be :subscribe" if ask && (ask = ask.to_sym) != :subscribe
+      if ask && (ask = ask.to_sym) != :subscribe
+        raise ArgumentError, "Invalid Type (#{ask}), can only be :subscribe"
+      end
       @ask = ask ? ask : nil
     end
 
-    ##
     # Set the status then sorts them according to priority
-    # presence:: Status
+    #
+    # @param [Blather::Stanza::Status] the new status
     def status=(presence)
       @statuses.delete_if { |s| s.from == presence.from }
       @statuses << presence
       @statuses.sort!
     end
 
-    ##
-    # Return the status with the highest priority
-    # if resource is set find the status of that specific resource 
+    # The status with the highest priority
+    #
+    # @param [String, nil] resource the resource to get the status of
     def status(resource = nil)
-      top = resource ? @statuses.detect { |s| s.from.resource == resource } : @statuses.first
+      top = if resource
+        @statuses.detect { |s| s.from.resource == resource }
+      else
+        @statuses.first
+      end
     end
 
-    ##
-    # Translate the RosterItem into a proper stanza that can be sent over the stream
+    # Translate the RosterItem into a proper stanza that can be sent over the
+    # stream
+    #
+    # @return [Blather::Stanza::Iq::Roster]
     def to_stanza(type = nil)
       r = Stanza::Iq::Roster.new type
       n = Stanza::Iq::Roster::RosterItem.new jid, name, subscription, ask

data/lib/blather/stanza.rb

@@ -1,95 +1,143 @@
 module Blather
-  ##
-  # Base XMPP Stanza
+
+  # # Base XMPP Stanza
+  #
+  # All stanzas inherit this class. It provides a set of methods and helpers
+  # common to all XMPP Stanzas
+  #
+  # @handler :stanza
   class Stanza < XMPPNode
+    # @private
     @@last_id = 0
+    # @private
     @@handler_list = []
 
-    class_inheritable_array :handler_heirarchy
+    class_inheritable_array :handler_hierarchy
 
-    ##
-    # Registers a callback onto the callback heirarchy stack
+    # Registers a callback onto the callback stack
     #
-    # Thanks to help from ActiveSupport every class
-    # that inherits Stanza can register a callback for itself
-    # which is added to a list and iterated over when looking for
-    # a callback to use
+    # @param [Symbol] handler the name of the handler
+    # @param [Symbol, String, nil] name the name of the first element in the
+    #        stanza. If nil the inherited name will be used. If that's nil the
+    #        handler name will be used.
+    # @param [String, nil] ns the namespace of the stanza
     def self.register(handler, name = nil, ns = nil)
       @@handler_list << handler
-      self.handler_heirarchy ||= []
-      self.handler_heirarchy.unshift handler
+      self.handler_hierarchy ||= [:stanza]
+      self.handler_hierarchy.unshift handler
 
       name = name || self.registered_name || handler
       super name, ns
     end
 
+    # The handler stack for the current stanza class
+    #
+    # @return [Array<Symbol>]
     def self.handler_list
       @@handler_list
     end
 
-    ##
     # Helper method that creates a unique ID for stanzas
+    #
+    # @return [String] a new unique ID
     def self.next_id
       @@last_id += 1
       'blather%04x' % @@last_id
     end
 
-    ##
-    # Helper method to generate stanza guard methods
-    #
-    # attribute_helpers_for(:type, [:subscribe, :unsubscribe])
+    # Check if the stanza is an error stanza
     #
-    # This generates "subscribe?" and "unsubscribe?" methods that return
-    # true if self.type == :subscribe or :unsubscribe, respectively.
-    def self.attribute_helpers_for(attr, values)
-      [values].flatten.each do |v|
-        define_method("#{v}?") { __send__(attr) == v }
-      end
+    # @return [true, false]
+    def error?
+      self.type == :error
     end
 
-    attribute_helpers_for(:type, :error)
-
-    ##
-    # Copies itself then swaps from and to
-    # then returns the new stanza
+    # Creates a copy with to and from swapped
+    #
+    # @return [Blather::Stanza]
     def reply
       self.dup.reply!
     end
 
-    ##
     # Swaps from and to
+    #
+    # @return [self]
     def reply!
       self.to, self.from = self.from, self.to
       self
     end
 
-    attribute_accessor :id
+    # Get the stanza's ID
+    #
+    # @return [String, nil]
+    def id
+      read_attr :id
+    end
 
-    attribute_writer :to, :from
+    # Set the stanza's ID
+    #
+    # @param [#to_s] id the new stanza ID
+    def id=(id)
+      write_attr :id, id
+    end
 
-    ##
-    # returns:: JID created from the "to" value of the stanza
+    # Get the stanza's to
+    #
+    # @return [Blather::JID, nil]
     def to
       JID.new(self[:to]) if self[:to]
     end
 
-    ##
-    # returns:: JID created from the "from" value of the stanza
+    # Set the stanza's to field
+    #
+    # @param [#to_s] to the new JID for the to field
+    def to=(to)
+      write_attr :to, to
+    end
+
+    # Get the stanza's from
+    #
+    # @return [Blather::JID, nil]
     def from
       JID.new(self[:from]) if self[:from]
     end
 
-    attribute_accessor :type, :call => :to_sym
+    # Set the stanza's from field
+    #
+    # @param [#to_s] from the new JID for the from field
+    def from=(from)
+      write_attr :from, from
+    end
 
-    ##
-    # Transform the stanza into a stanza error
-    # <tt>err_name_or_class</tt> can be the name of the error or the error class to use
-    # <tt>type</tt>, <tt>text</tt>, <tt>extras</tt> are the same as for StanzaError#new
+    # Get the stanza's type
+    #
+    # @return [Symbol, nil]
+    def type
+      read_attr :type, :to_sym
+    end
+
+    # Set the stanza's type
+    #
+    # @param [#to_s] type the new stanza type
+    def type=(type)
+      write_attr :type, type
+    end
+
+    # Create an error stanza from the current stanza
+    #
+    # @param [String] name the error name
+    # @param [<Blather::StanzaError::VALID_TYPES>] type the error type
+    # @param [String, nil] text the error text
+    # @param [Array<XML::Node>] extras an array of extra nodes to attach to
+    # the error
+    #
+    # @return [Blather::StanzaError]
     def as_error(name, type, text = nil, extras = [])
       StanzaError.new self, name, type, text, extras
     end
 
-    protected
+  protected
+    # @private
     def reply_if_needed!
       unless @reversed_endpoints
         reply!

data/lib/blather/stanza/disco.rb

@@ -1,15 +1,25 @@
 module Blather
 class Stanza
 
+  # # Disco Base class
+  #
+  # Use Blather::Stanza::DiscoInfo or Blather::Stanza::DiscoItems
   class Disco < Iq::Query
+
+    # Get the name of the node
+    #
+    # @return [String] the node name
     def node
       query[:node]
     end
 
+    # Set the name of the node
+    #
+    # @param [#to_s] node the new node name
     def node=(node)
       query[:node] = node
     end
   end
 
-end #Stanza
-end #Blather
+end # Stanza
+end # Blather