Add documentation to Utils methods

lib/twitter/client/friendship.rb

@@ -70,9 +70,9 @@ def friendship_exists?(user_a, user_b, options={})
       # @param user_a [Integer, String] The ID or screen_name of the subject user.
       # @param user_b [Integer, String] The ID or screen_name of the user to test for following.
       # @param options [Hash] A customizable set of options.
-      # @option options [Integer] :source_id The user_id of the subject user.
+      # @option options [Integer] :source_id The ID of the subject user.
       # @option options [String] :source_screen_name The screen_name of the subject user.
-      # @option options [Integer] :target_id The user_id of the target user.
+      # @option options [Integer] :target_id The ID of the target user.
       # @option options [String] :target_screen_name The screen_name of the target user.
       # @return [Hashie::Mash]
       # @see http://dev.twitter.com/doc/get/friendships/show

lib/twitter/client/utils.rb

@@ -13,11 +13,18 @@ def get_screen_name
       end
 
       # Remove @ signs from screen names
+      #
+      # @param screen_name [String] A Twitter screen name.
+      # @return [String] The Twitter screen name minus the @ sign.
       def clean_screen_name!(screen_name)
         screen_name.gsub!(/[@＠]/, '') if screen_name
       end
 
       # Take a single user ID or screen name and merge it into an options hash with the correct key
+      #
+      # @param user_id_or_screen_name [Integer, String] A Twitter user ID or screen_name.
+      # @param options [Hash] A customizable set of options.
+      # @return [Hash]
       def merge_user_into_options!(user_id_or_screen_name, options={})
         case user_id_or_screen_name
         when Fixnum
@@ -30,6 +37,10 @@ def merge_user_into_options!(user_id_or_screen_name, options={})
       end
 
       # Take a multiple user IDs and screen names and merge them into an options hash with the correct keys
+      #
+      # @param users_id_or_screen_names [Array] An array of Twitter user IDs or screen_names.
+      # @param options [Hash] A customizable set of options.
+      # @return [Hash]
       def merge_users_into_options!(user_ids_or_screen_names, options={})
         user_ids, screen_names = [], []
         user_ids_or_screen_names.flatten.each do |user_id_or_screen_name|