lib/blather/roster_item.rb in blather-0.4.7 vs lib/blather/roster_item.rb in blather-0.4.8

@@ -1,12 +1,11 @@
 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,
                 :statuses
 
@@ -16,12 +15,23 @@
     def self.new(item)
       return item if item.is_a?(self)
       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 = []
 
       case item
@@ -38,57 +48,69 @@
       end
 
       @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
       r.query << n
       n.groups = groups
\ No newline at end of file