Document Twitter::Client::Account

lib/faraday/multipart.rb

@@ -1,7 +1,7 @@
 require 'faraday'
 
+# @api private
 module Faraday
-  # @api private
   class Request::Multipart < Faraday::Middleware
     def call(env)
       if env[:body].is_a?(Hash)

lib/faraday/oauth.rb

@@ -1,8 +1,8 @@
 require 'faraday'
 require 'simple_oauth'
 
+# @api private
 module Faraday
-  # @api private
   class Request::OAuth < Faraday::Middleware
     def call(env)
       params = env[:body].is_a?(Hash) ? env[:body] : {}

lib/faraday/raise_http_4xx.rb

@@ -1,7 +1,7 @@
 require 'faraday'
 
+# @api private
 module Faraday
-  # @api private
   class Response::RaiseHttp4xx < Response::Middleware
     def self.register_on_complete(env)
       env[:response].on_complete do |response|

lib/faraday/raise_http_5xx.rb

@@ -1,7 +1,7 @@
 require 'faraday'
 
+# @api private
 module Faraday
-  # @api private
   class Response::RaiseHttp5xx < Response::Middleware
     def self.register_on_complete(env)
       env[:response].on_complete do |response|

lib/twitter/base.rb

@@ -2,15 +2,15 @@ module Twitter
   class Base
     # Alias for Twitter::Client.new
     #
-    # @deprecated {Twitter::Base} is deprecated and will be permanently removed in the next major version. Please use {Twitter::Client} instead."
+    # @deprecated {Twitter::Base#client} is deprecated and will be permanently removed in the next major version. Please use Twitter::Client.new instead.
     # @return [Twitter::Client]
     def client(options={})
       Twitter::Client.new(options)
     end
 
     # Delegate to Twitter::Client
     #
-    # @deprecated {Twitter::Base} is deprecated and will be permanently removed in the next major version. Please use {Twitter::Client} instead."
+    # @deprecated {Twitter::Base} is deprecated and will be permanently removed in the next major version. Please use {Twitter::Client} instead.
     def method_missing(method, *args, &block)
       return super unless client.respond_to?(method)
       warn "#{Kernel.caller.first}: [DEPRECATION] Twitter::Base##{method} is deprecated and will be permanently removed in the next major version. Please use Twitter::Client##{method} instead."

lib/twitter/client/account.rb

@@ -1,41 +1,143 @@
 module Twitter
   class Client
     module Account
+      # Returns the requesting user if authentication was successful, otherwise raises {Twitter::Unauthorized}
+      #
+      # @format :json, :xml
+      # @authenticated true
+      # @rate_limited true
+      # @param options [Hash] A customizable set of options.
+      # @option options [Boolean, String, Integer] :include_entities Include {http://dev.twitter.com/pages/tweet_entities Tweet Entities} when set to true, 't' or 1.
+      # @return [Hashie::Mash] The authenticated user.
+      # @raise [Twitter::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @see http://dev.twitter.com/doc/get/account/verify_credentials
+      # @example Return the requesting user if authentication was successful
+      #   Twitter.verify_credentials
       def verify_credentials(options={})
         response = get('account/verify_credentials', options)
         format.to_s.downcase == 'xml' ? response['user'] : response
       end
 
+      # Returns the remaining number of API requests available to the requesting user
+      #
+      # @format :json, :xml
+      # @authenticated [false] This will return the requesting IP's rate limit status. If you want the authenticating user's rate limit status you must authenticate.
+      # @rate_limited true
+      # @param options [Hash] A customizable set of options.
+      # @return [Hashie::Mash]
+      # @see http://dev.twitter.com/doc/get/account/rate_limit_status
+      # @example Return the remaining number of API requests available to the requesting user
+      #   Twitter.rate_limit_status
       def rate_limit_status(options={})
         response = get('account/rate_limit_status', options)
         format.to_s.downcase == 'xml' ? response['hash'] : response
       end
 
+      # Ends the session of the authenticating user
+      #
+      # @format :json, :xml
+      # @authenticated true
+      # @rate_limited false
+      # @param options [Hash] A customizable set of options.
+      # @return [Hashie::Mash]
+      # @see http://dev.twitter.com/doc/post/account/end_session
+      # @example End the sessions of the authenticating user
+      #   Twitter.end_session
       def end_session(options={})
         response = post('account/end_session', options)
         format.to_s.downcase == 'xml' ? response['hash'] : response
       end
 
+      # Sets which device Twitter delivers updates to for the authenticating user
+      #
+      # @format :json, :xml
+      # @authenticated true
+      # @rate_limited false
+      # @param device [String] Must be one of: 'sms', 'none'.
+      # @param options [Hash] A customizable set of options.
+      # @option options [Boolean, String, Integer] :include_entities Include {http://dev.twitter.com/pages/tweet_entities Tweet Entities} when set to true, 't' or 1.
+      # @return [Hashie::Mash] The authenticated user.
+      # @see http://dev.twitter.com/doc/post/account/update_delivery_device
+      # @example Turn SMS updates on for the authenticating user
+      #   Twitter.update_delivery_device('sms')
       def update_delivery_device(device, options={})
         response = post('account/update_delivery_device', options.merge(:device => device))
         format.to_s.downcase == 'xml' ? response['user'] : response
       end
 
+      # Sets one or more hex values that control the color scheme of the authenticating user's profile
+      #
+      # @format :json, :xml
+      # @authenticated true
+      # @rate_limited false
+      # @param options [Hash] A customizable set of options.
+      # @option options [String] :profile_background_color Profile background color.
+      # @option options [String] :profile_text_color Profile text color.
+      # @option options [String] :profile_link_color Profile link color.
+      # @option options [String] :profile_sidebar_fill_color Profile sidebar's background color.
+      # @option options [String] :profile_sidebar_border_color Profile sidebar's border color.
+      # @option options [Boolean, String, Integer] :include_entities Include {http://dev.twitter.com/pages/tweet_entities Tweet Entities} when set to true, 't' or 1.
+      # @return [Hashie::Mash] The authenticated user.
+      # @see http://dev.twitter.com/doc/post/account/update_profile_colors
+      # @example Set authenticating user's profile background to black
+      #   Twitter.update_profile_colors(:profile_background_color => '000000')
       def update_profile_colors(options={})
         response = post('account/update_profile_colors', options)
         format.to_s.downcase == 'xml' ? response['user'] : response
       end
 
-      def update_profile_image(file, options={})
-        response = post('account/update_profile_image', options.merge(:image => file))
+      # Updates the authenticating user's profile image
+      # @note This method asynchronously processes the uploaded file before updating the user's profile image URL. You can either update your local cache the next time you request the user's information, or, at least 5 seconds after uploading the image, ask for the updated URL using {Twitter::Client::User#profile_image}.
+      #
+      # @format :json, :xml
+      # @authenticated true
+      # @rate_limited false
+      # @param image [String] The avatar image for the profile. Must be a valid GIF, JPG, or PNG image of less than 700 kilobytes in size. Images with width larger than 500 pixels will be scaled down. Animated GIFs will be converted to a static GIF of the first frame, removing the animation.
+      # @param options [Hash] A customizable set of options.
+      # @option options [Boolean, String, Integer] :include_entities Include {http://dev.twitter.com/pages/tweet_entities Tweet Entities} when set to true, 't' or 1.
+      # @return [Hashie::Mash] The authenticated user.
+      # @see http://dev.twitter.com/doc/post/account/update_profile_image
+      # @example Update the authenticating user's profile image
+      #   Twitter.update_profile_image(File.new("me.jpeg"))
+      def update_profile_image(image, options={})
+        response = post('account/update_profile_image', options.merge(:image => image))
         format.to_s.downcase == 'xml' ? response['user'] : response
       end
 
-      def update_profile_background_image(file, options={})
-        response = post('account/update_profile_background_image', options.merge(:image => file))
+      # Updates the authenticating user's profile background image
+      #
+      # @format :json, :xml
+      # @authenticated true
+      # @rate_limited false
+      # @param image [String] The background image for the profile. Must be a valid GIF, JPG, or PNG image of less than 800 kilobytes in size. Images with width larger than 2048 pixels will be forceably scaled down.
+      # @param options [Hash] A customizable set of options.
+      # @option options [Boolean] :tile Whether or not to tile the background image. If set to true the background image will be displayed tiled. The image will not be tiled otherwise.
+      # @option options [Boolean, String, Integer] :include_entities Include {http://dev.twitter.com/pages/tweet_entities Tweet Entities} when set to true, 't' or 1.
+      # @return [Hashie::Mash] The authenticated user.
+      # @see http://dev.twitter.com/doc/post/account/update_profile_background_image
+      # @example Update the authenticating user's profile background image
+      #   Twitter.update_profile_background_image(File.new("we_concept_bg2.png"))
+      def update_profile_background_image(image, options={})
+        response = post('account/update_profile_background_image', options.merge(:image => image))
         format.to_s.downcase == 'xml' ? response['user'] : response
       end
 
+      # Sets values that users are able to set under the "Account" tab of their settings page
+      # @note Only the options specified will be updated.
+      #
+      # @format :json, :xml
+      # @authenticated true
+      # @rate_limited false
+      # @param options [Hash] A customizable set of options.
+      # @option options [String] :name Full name associated with the profile. Maximum of 20 characters.
+      # @option options [String] :url URL associated with the profile. Will be prepended with "http://" if not present. Maximum of 100 characters.
+      # @option options [String] :location The city or country describing where the user of the account is located. The contents are not normalized or geocoded in any way. Maximum of 30 characters.
+      # @option options [String] :description A description of the user owning the account. Maximum of 160 characters.
+      # @option options [Boolean, String, Integer] :include_entities Include {http://dev.twitter.com/pages/tweet_entities Tweet Entities} when set to true, 't' or 1.
+      # @return [Hashie::Mash] The authenticated user.
+      # @see http://dev.twitter.com/doc/post/account/update_profile
+      # @example Set authenticating user's name to Erik Michaels-Ober
+      #   Twitter.update_profile(:name => "Erik Michaels-Ober")
       def update_profile(options={})
         response = post('account/update_profile', options)
         format.to_s.downcase == 'xml' ? response['user'] : response

lib/twitter/client/geo.rb

@@ -79,7 +79,7 @@ def reverse_geocode(options={})
       # @rate_limited true
       # @param place_id [String] A place in the world. These IDs can be retrieved from {Twitter::Client::Geo#reverse_geocode}.
       # @param options [Hash] A customizable set of options.
-      # @return [Hashie::Mash] The requested place object.
+      # @return [Hashie::Mash] The requested place.
       # @see http://dev.twitter.com/doc/get/geo/id/:place_id
       # @example Return all the information about Twitter HQ
       #   Twitter.place("247f43d441defc03")
@@ -99,7 +99,7 @@ def place(place_id, options={})
       # @option options [Float] :lat The latitude to search around. This option will be ignored unless it is inside the range -90.0 to +90.0 (North is positive) inclusive. It will also be ignored if there isn't a corresponding :long option.
       # @option options [Float] :long The longitude to search around. The valid ranges for longitude is -180.0 to +180.0 (East is positive) inclusive. This option will be ignored if outside that range, if it is not a number, if geo_enabled is disabled, or if there not a corresponding :lat option.
       # @option options [String] :"attribute:street_address" This option searches for places which have this given street address. There are other well-known, and application specific attributes available. Custom attributes are also permitted.
-      # @return [Hashie::Mash] The created place object.
+      # @return [Hashie::Mash] The created place.
       # @see http://dev.twitter.com/doc/post/geo/place
       # @example Create a new place
       #   Twitter.place_create(:name => "@sferik's Apartment", :token => "22ff5b1f7159032cf69218c4d8bb78bc", :contained_within => "41bcb736f84a799e", :lat => "37.783699", :long => "-122.393581")

lib/twitter/client/user.rb

@@ -8,8 +8,8 @@ module User
       # @rate_limited true
       # @param user [String, Integer] A Twitter user ID or screen name.
       # @param options [Hash] A customizable set of options.
-      # @option options [String] :include_entities Include {http://dev.twitter.com/pages/tweet_entities Tweet Entities} when set to true, 't' or 1.
-      # @return [Hashie::Mash] The requested user object.
+      # @option options [Boolean, String, Integer] :include_entities Include {http://dev.twitter.com/pages/tweet_entities Tweet Entities} when set to true, 't' or 1.
+      # @return [Hashie::Mash] The requested user.
       # @see http://dev.twitter.com/doc/get/users/show
       # @example Return extended information for @sferik
       #   Twitter.user("sferik")
@@ -20,18 +20,18 @@ def user(user, options={})
         format.to_s.downcase == 'xml' ? response['user'] : response
       end
 
-      # Returns extended information of a given user
+      # Return up to 100 users worth of extended information
       #
       # @format :json, :xml
       # @authenticated true
       # @rate_limited true
       # @overload users(*users, options={})
       #   @param users [String, Integer] Twitter users ID or screen names.
       #   @param options [Hash] A customizable set of options.
-      #   @option options [String] :include_entities Include {http://dev.twitter.com/pages/tweet_entities Tweet Entities} when set to true, 't' or 1.
-      # @return [Hashie::Mash] The requested user object.
+      #   @option options [Boolean, String, Integer] :include_entities Include {http://dev.twitter.com/pages/tweet_entities Tweet Entities} when set to true, 't' or 1.
+      # @return [Array] The requested users.
       # @see http://dev.twitter.com/doc/get/users/lookup
-      # @example Return extended information for @sferik
+      # @example Return extended information for @sferik and @pengwynn
       #   Twitter.user("sferik", "pengwynn")
       #   Twitter.user("sferik", 14100886)   # Same as above
       #   Twitter.user(7505382, 14100886)    # Same as above
@@ -52,7 +52,7 @@ def users(*args)
       # @param options [Hash] A customizable set of options.
       # @option options [Integer] :per_page The number of people to retrieve. Maxiumum of 20 allowed per page.
       # @option options [Integer] :page Specifies the page of results to retrieve.
-      # @option options [String] :include_entities Include {http://dev.twitter.com/pages/tweet_entities Tweet Entities} when set to true, 't' or 1.
+      # @option options [Boolean, String, Integer] :include_entities Include {http://dev.twitter.com/pages/tweet_entities Tweet Entities} when set to true, 't' or 1.
       # @return [Array]
       # @see http://dev.twitter.com/doc/get/users/search
       # @example Return users that match "Erik Michaels-Ober"
@@ -112,15 +112,15 @@ def profile_image(screen_name, options={})
       # @overload friends(options={})
       #   @param options [Hash] A customizable set of options.
       #   @option options [String] :cursor (-1) Breaks the results into pages. This is recommended for users who are following many users. Provide a value of -1 to begin paging. Provide values as returned in the response body's next_cursor and previous_cursor attributes to page back and forth in the list.
-      #   @option options [String] :include_entities Include {http://dev.twitter.com/pages/tweet_entities Tweet Entities} when set to true, 't' or 1.
+      #   @option options [Boolean, String, Integer] :include_entities Include {http://dev.twitter.com/pages/tweet_entities Tweet Entities} when set to true, 't' or 1.
       #   @return [Hashie::Mash]
       #   @example Return the authenticated user's friends
       #     Twitter.freinds
       # @overload friends(user, options={})
       #   @param user [String, Integer] A Twitter user ID or screen name.
       #   @param options [Hash] A customizable set of options.
       #   @option options [String] :cursor (-1) Breaks the results into pages. This is recommended for users who are following many users. Provide a value of -1 to begin paging. Provide values as returned in the response body's next_cursor and previous_cursor attributes to page back and forth in the list.
-      #   @option options [String] :include_entities Include {http://dev.twitter.com/pages/tweet_entities Tweet Entities} when set to true, 't' or 1.
+      #   @option options [Boolean, String, Integer] :include_entities Include {http://dev.twitter.com/pages/tweet_entities Tweet Entities} when set to true, 't' or 1.
       #   @return [Hashie::Mash]
       #   @example Return the @sferik's friends
       #     Twitter.friends("sferik")
@@ -147,15 +147,15 @@ def friends(*args)
       # @overload followers(options={})
       #   @param options [Hash] A customizable set of options.
       #   @option options [String] :cursor (-1) Breaks the results into pages. Provide values as returned in the response object's next_cursor and previous_cursor attributes to page back and forth in the list.
-      #   @option options [String] :include_entities Include {http://dev.twitter.com/pages/tweet_entities Tweet Entities} when set to true, 't' or 1.
+      #   @option options [Boolean, String, Integer] :include_entities Include {http://dev.twitter.com/pages/tweet_entities Tweet Entities} when set to true, 't' or 1.
       #   @return [Hashie::Mash]
       #   @example Return the authenticated user's followers
       #     Twitter.freinds
       # @overload followers(user, options={})
       #   @param user [String, Integer] A Twitter user ID or screen name.
       #   @param options [Hash] A customizable set of options.
       #   @option options [String] :cursor (-1) Breaks the results into pages. Provide values as returned in the response objects's next_cursor and previous_cursor attributes to page back and forth in the list.
-      #   @option options [String] :include_entities Include {http://dev.twitter.com/pages/tweet_entities Tweet Entities} when set to true, 't' or 1.
+      #   @option options [Boolean, String, Integer] :include_entities Include {http://dev.twitter.com/pages/tweet_entities Tweet Entities} when set to true, 't' or 1.
       #   @return [Hashie::Mash]
       #   @example Return the @sferik's followers
       #     Twitter.followers("sferik")