From 7873b0306d5fb1f27e4061cd024ab43589441fa4 Mon Sep 17 00:00:00 2001 From: Diana Kimball Date: Sun, 7 Nov 2010 02:41:42 +0800 Subject: [PATCH] Copy-edit documentation --- README.mkd | 20 ++++++---- lib/twitter/client/account.rb | 8 ++-- lib/twitter/client/favorites.rb | 6 +-- lib/twitter/client/friends_and_followers.rb | 22 ++++++----- lib/twitter/client/geo.rb | 32 +++++++--------- lib/twitter/client/list.rb | 2 +- lib/twitter/client/local_trends.rb | 4 +- lib/twitter/client/timeline.rb | 42 ++++++++++----------- lib/twitter/client/tweets.rb | 20 +++++----- lib/twitter/client/user.rb | 18 +++++---- 10 files changed, 91 insertions(+), 83 deletions(-) diff --git a/README.mkd b/README.mkd index ca7d6b820..7b5cdce8a 100644 --- a/README.mkd +++ b/README.mkd @@ -13,7 +13,7 @@ Installation What's new in 1.0? ------------------ This gem has been completely rewritten for version 1.0 thanks to [contributions from numerous -people](http://github.com/jnunemaker/twitter/blob/master/HISTORY.md). This rewrite breaks +people](http://github.com/jnunemaker/twitter/blob/master/HISTORY.mkd). This rewrite breaks compatibility with version 0.9.12 and earlier versions of the gem. Most notably, the Twitter::Base, Twitter:Geo, Twitter::LocalTrends, and Twitter::Trends classes [have all been merged](http://github.com/jnunemaker/twitter/commit/eb53872249634ee1f0179982b091a1a0fd9c0973) into @@ -105,7 +105,7 @@ thing ([twitter-auth](http://github.com/mbleigh/twitter-auth), [devise](http://github.com/plataformatec/devise), to name a few) we decided to decouple this functionality so you can use the authentication library of your choosing, or none at all. If you would like to continue using the [oauth gem](http://github.com/oauth/oauth-ruby), -simply require it and make the following changes: +simply apply the following changes to your code: * **Pre-1.0** options = {:api_endpoint => "http://api.twitter.com", :signing_endpoint => "http://api.twitter.com"} @@ -117,6 +117,7 @@ simply require it and make the following changes: oauth_wrapper.authorize_from_request(request_token.token, request_token.secret, params[:oauth_verifier]) * **Post-1.0** + require 'oauth' options = {:site => "http://api.twitter.com", :request_endpoint => "http://api.twitter.com"} signing_consumer = OAuth::Consumer.new(YOUR_CONSUMER_TOKEN, YOUR_CONSUMER_SECRET, options) request_token = signing_consumer.get_request_token(:oauth_callback => CALLBACK_URL) @@ -125,13 +126,13 @@ simply require it and make the following changes: The public APIs defined in version 1.0 of this gem will maintain backwards compatibility until the next major version, following the best practice of [Semantic Versioning](http://semver.org/). -You are free to continue using the 0.9 series of the gem, however it will not be maintained, so +You are free to continue using the 0.9 series of the gem; however, it will not be maintained so upgrading to 1.0 is strongly recommended. Here are a few more reasons to upgrade to 1.0: * Ruby 1.9 compatibility: All code and specs now work in the latest version of Ruby! -* Support for HTTP proxies: Access Twitter from from China, Iran, or inside your office firewall! +* Support for HTTP proxies: Access Twitter from China, Iran, or inside your office firewall! * Support for multiple HTTP adapters: NetHttp (default), Typhoeus, Patron, or ActionDispatch * Support for multiple request formats: JSON (default) or XML * More flexible: Parse JSON or XML with the engine of your choosing via [MultiJSON](http://github.com/intridea/multi_json) and [MultiXML](http://github.com/sferik/multi_xml) @@ -140,7 +141,8 @@ Here are a few more reasons to upgrade to 1.0: * SSL: On by default for increased [speed](http://gist.github.com/652330) and security! * Improved error handling: Easily rescue and retry after rate-limit errors or fail whales! -For more information, please see the (full documentation)[http://rdoc.info/gems/twitter] and examples of the gem's usage below. +For more information, please see the [full documentation](http://rdoc.info/gems/twitter) and +examples of the gem's usage below. Help! I'm getting: "Did not recognize your engine specification. Please specify either a symbol or a class. (RuntimeError)" --------------------------------------------------------------------------------------------------------------------------- @@ -222,13 +224,14 @@ Here are some ways *you* can contribute: * by suggesting new features * by writing or editing documentation * by writing specifications -* by writing code (**no patch is too small**: fix typos, add comments, cleanup inconsistent whitespace) +* by writing code (**no patch is too small**: fix typos, add comments, clean up inconsistent whitespace) * by refactoring code * by closing [issues](http://github.com/jnunemaker/twitter/issues) * by reviewing patches * [financially](http://pledgie.com/campaigns/1193) -All contributors will be added to the [HISTORY](https://github.com/jnunemaker/twitter/blob/master/HISTORY.mkd) file and will receive the respect and gratitude of the community. +All contributors will be added to the [HISTORY](https://github.com/jnunemaker/twitter/blob/master/HISTORY.mkd) +file and will receive the respect and gratitude of the community. Submitting an Issue ------------------- @@ -252,4 +255,5 @@ Submitting a Pull Request Copyright --------- -Copyright (c) 2010 John Nunemaker, Wynn Netherland, Erik Michaels-Ober, Steve Richert. See LICENSE for details. +Copyright (c) 2010 John Nunemaker, Wynn Netherland, Erik Michaels-Ober, Steve Richert. +See [LICENSE](https://github.com/jnunemaker/twitter/blob/master/LICENSE.mkd) for details. diff --git a/lib/twitter/client/account.rb b/lib/twitter/client/account.rb index 7ccd9f3b4..2ae721fac 100644 --- a/lib/twitter/client/account.rb +++ b/lib/twitter/client/account.rb @@ -21,7 +21,9 @@ def verify_credentials(options={}) # 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. + # @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] @@ -41,7 +43,7 @@ def rate_limit_status(options={}) # @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 + # @example End the session of the authenticating user # Twitter.end_session def end_session(options={}) response = post('account/end_session', options) @@ -109,7 +111,7 @@ def update_profile_image(image, options={}) # @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 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 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. diff --git a/lib/twitter/client/favorites.rb b/lib/twitter/client/favorites.rb index 757649abe..8460cbde4 100644 --- a/lib/twitter/client/favorites.rb +++ b/lib/twitter/client/favorites.rb @@ -11,7 +11,7 @@ module Favorites # @example Return the 20 most recent favorite statuses for the authenticating user # Twitter.favorites # @overload favorites(user, options={}) - # Returns the 20 most recent favorite statuses for the user specified by the user parameter + # Returns the 20 most recent favorite statuses for the specified user # # @param user [Integer, String] A Twitter user ID or screen name. # @param options [Hash] A customizable set of options. @@ -31,7 +31,7 @@ def favorites(*args) format.to_s.downcase == 'xml' ? response['statuses'] : response end - # Favorites the status specified in the ID parameter as the authenticating user + # Favorites the specified status as the authenticating user # # @format :json, :xml # @authenticated true @@ -48,7 +48,7 @@ def favorite_create(id, options={}) format.to_s.downcase == 'xml' ? response['status'] : response end - # Un-favorites the status specified in the ID parameter as the authenticating user + # Un-favorites the specified status as the authenticating user # # @format :json, :xml # @authenticated true diff --git a/lib/twitter/client/friends_and_followers.rb b/lib/twitter/client/friends_and_followers.rb index 9d30f12b0..21bfbd54a 100644 --- a/lib/twitter/client/friends_and_followers.rb +++ b/lib/twitter/client/friends_and_followers.rb @@ -8,21 +8,23 @@ module FriendsAndFollowers # @param options [Hash] A customizable set of options. # @option options [Integer] :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. # @return [Array] Numeric IDs. - # @example Return the authenticated user's friends IDs - # Twitter.freinds_ids + # @example Return the authenticated user's friends' IDs + # Twitter.friend_ids # @overload friend_ids(user, options={}) # Returns an array of numeric IDs for every user the specified user is following # # @param user [Integer, String] A Twitter user ID or screen name. # @param options [Hash] A customizable set of options. # @option options [Integer] :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. - # @return [Hashie::Mash] - # @example Return @sferik's friends IDs + # @return [Array] Numeric IDs. + # @example Return @sferik's friends' IDs # Twitter.friend_ids("sferik") # Twitter.friend_ids(7505382) # Same as above # @see http://dev.twitter.com/doc/get/friends/ids # @format :json, :xml - # @authenticated false unless requesting it from a protected user; if getting this data of a protected user, you must auth (and be allowed to see that user). + # @authenticated false unless requesting it from a protected user + # + # If getting this data of a protected user, you must authenticate (and be allowed to see that user). # @rate_limited true def friend_ids(*args) options = {:cursor => -1} @@ -40,7 +42,7 @@ def friend_ids(*args) # @param options [Hash] A customizable set of options. # @option options [Integer] :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. # @return [Array] Numeric IDs. - # @example Return the authenticated user's followers IDs + # @example Return the authenticated user's followers' IDs # Twitter.follower_ids # @overload follower_ids(user, options={}) # Returns an array of numeric IDs for every user following the specified user @@ -48,13 +50,15 @@ def friend_ids(*args) # @param user [Integer, String] A Twitter user ID or screen name. # @param options [Hash] A customizable set of options. # @option options [Integer] :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. - # @return [Hashie::Mash] - # @example Return @sferik's followers IDs + # @return [Array] Numeric IDs. + # @example Return @sferik's followers' IDs # Twitter.follower_ids("sferik") # Twitter.follower_ids(7505382) # Same as above # @see http://dev.twitter.com/doc/get/followers/ids # @format :json, :xml - # @authenticated false unless requesting it from a protected user; if getting this data of a protected user, you must auth (and be allowed to see that user). + # @authenticated false unless requesting it from a protected user + # + # If getting this data of a protected user, you must authenticate (and be allowed to see that user). # @rate_limited true def follower_ids(*args) options = {:cursor => -1} diff --git a/lib/twitter/client/geo.rb b/lib/twitter/client/geo.rb index de3b7c044..a13dc026c 100644 --- a/lib/twitter/client/geo.rb +++ b/lib/twitter/client/geo.rb @@ -9,14 +9,14 @@ module Geo # @rate_limited true # @param options [Hash] A customizable set of 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 [Float] :long The longitude to search around. The valid range 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] :query Free-form text to match against while executing a geo-based query, best suited for finding nearby locations by name. # @option options [String] :ip An IP address. Used when attempting to fix geolocation based off of the user's IP address. - # @option options [String] :granularity This is the minimal granularity of place types to return and must be one of: 'poi', 'neighborhood', 'city', 'admin' or 'country'. If no granularity is provided for the request neighborhood is assumed. - # @option options [String] :accuracy A hint on the "region" in which to search. If a number, then this is a radius in meters, but it can also take a string that is suffixed with ft to specify feet. If this is not passed in, then it is assumed to be 0m. If coming from a device, in practice, this value is whatever accuracy the device has measuring its location (whether it be coming from a GPS, WiFi triangulation, etc.). + # @option options [String] :granularity ('neighborhood') This is the minimal granularity of place types to return and must be one of: 'poi', 'neighborhood', 'city', 'admin' or 'country'. + # @option options [String] :accuracy ('0m') A hint on the "region" in which to search. If a number, then this is a radius in meters, but it can also take a string that is suffixed with ft to specify feet. If coming from a device, in practice, this value is whatever accuracy the device has measuring its location (whether it be coming from a GPS, WiFi triangulation, etc.). # @option options [Integer] :max_results A hint as to the number of results to return. This does not guarantee that the number of results returned will equal max_results, but instead informs how many "nearby" results to return. Ideally, only pass in the number of places you intend to display to the user here. # @option options [String] :contained_within This is the place_id which you would like to restrict the search results to. Setting this value means only places within the given place_id will be found. - # @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. + # @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 [Array] # @see http://dev.twitter.com/doc/get/geo/search # @example Return an array of places near the IP address 74.125.19.104 @@ -28,21 +28,16 @@ def places_nearby(options={}) # Locates places near the given coordinates which are similar in name # - # Conceptually you would use this method to get a list of known places to choose from first. - # Then, if the desired place doesn't exist, make a request to {Twitter::Client::Geo#place} - # to create a new one. - # - # The token contained in the response is the token needed to be able to create a new place. - # + # @note Conceptually, you would use this method to get a list of known places to choose from first. Then, if the desired place doesn't exist, make a request to {Twitter::Client::Geo#place} to create a new one. The token contained in the response is the token necessary to create a new place. # @format :json # @authenticated false # @rate_limited true # @param options [Hash] A customizable set of 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 [Float] :long The longitude to search around. The valid range 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] :name The name a place is known as. # @option options [String] :contained_within This is the place_id which you would like to restrict the search results to. Setting this value means only places within the given place_id will be found. - # @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. + # @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 [Array] # @see http://dev.twitter.com/doc/get/geo/similar_places # @example Return an array of places similar to Twitter HQ @@ -53,16 +48,15 @@ def places_similar(options={}) # Searches for up to 20 places that can be used as a place_id # - # This request is an informative call and will deliver generalized results about geography. - # + # @note This request is an informative call and will deliver generalized results about geography. # @format :json # @authenticated false # @rate_limited true # @param options [Hash] A customizable set of 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] :accuracy A hint on the "region" in which to search. If a number, then this is a radius in meters, but it can also take a string that is suffixed with ft to specify feet. If this is not passed in, then it is assumed to be 0m. If coming from a device, in practice, this value is whatever accuracy the device has measuring its location (whether it be coming from a GPS, WiFi triangulation, etc.). - # @option options [String] :granularity This is the minimal granularity of place types to return and must be one of: 'poi', 'neighborhood', 'city', 'admin' or 'country'. If no granularity is provided for the request neighborhood is assumed. + # @option options [Float] :long The longitude to search around. The valid range 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] :accuracy ('0m') A hint on the "region" in which to search. If a number, then this is a radius in meters, but it can also take a string that is suffixed with ft to specify feet. If coming from a device, in practice, this value is whatever accuracy the device has measuring its location (whether it be coming from a GPS, WiFi triangulation, etc.). + # @option options [String] :granularity ('neighborhood') This is the minimal granularity of place types to return and must be one of: 'poi', 'neighborhood', 'city', 'admin' or 'country'. # @option options [Integer] :max_results A hint as to the number of results to return. This does not guarantee that the number of results returned will equal max_results, but instead informs how many "nearby" results to return. Ideally, only pass in the number of places you intend to display to the user here. # @return [Array] # @see http://dev.twitter.com/doc/get/geo/reverse_geocode @@ -97,8 +91,8 @@ def place(place_id, options={}) # @option options [String] :contained_within This is the place_id which you would like to restrict the search results to. Setting this value means only places within the given place_id will be found. # @option options [String] :token The token found in the response from {Twitter::Client::Geo#places_similar}. # @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. + # @option options [Float] :long The longitude to search around. The valid range 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. # @see http://dev.twitter.com/doc/post/geo/place # @example Create a new place diff --git a/lib/twitter/client/list.rb b/lib/twitter/client/list.rb index 62e066c7b..239e79b76 100644 --- a/lib/twitter/client/list.rb +++ b/lib/twitter/client/list.rb @@ -46,7 +46,7 @@ def list_update(screen_name, name, options={}) # List the lists of the specified user # - # @note Private lists will be included if the authenticated users is the same as the user who's lists are being returned. + # @note Private lists will be included if the authenticated user is the same as the user whose lists are being returned. # @overload lists(options={}) # @param options [Hash] A customizable set of options. # @option options [Integer] :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. diff --git a/lib/twitter/client/local_trends.rb b/lib/twitter/client/local_trends.rb index 561a90425..fa0c7c4e6 100644 --- a/lib/twitter/client/local_trends.rb +++ b/lib/twitter/client/local_trends.rb @@ -7,8 +7,8 @@ module LocalTrends # @authenticated false # @rate_limited true # @param options [Hash] A customizable set of options. - # @option options [Float] :lat If provided with a :long option the available trend locations will be sorted by distance, nearest to furthest, to the co-ordinate pair. The valid ranges for latitude is -90.0 to +90.0 (North is positive) inclusive. - # @option options [Float] :long If provided with a :lat option the available trend locations will be sorted by distance, nearest to furthest, to the co-ordinate pair. The valid ranges for longitude is -180.0 to +180.0 (East is positive) inclusive. + # @option options [Float] :lat If provided with a :long option the available trend locations will be sorted by distance, nearest to furthest, to the co-ordinate pair. The valid ranges for latitude are -90.0 to +90.0 (North is positive) inclusive. + # @option options [Float] :long If provided with a :lat option the available trend locations will be sorted by distance, nearest to furthest, to the co-ordinate pair. The valid ranges for longitude are -180.0 to +180.0 (East is positive) inclusive. # @return [Array] # @see http://dev.twitter.com/doc/get/trends/available # @example Return the locations that Twitter has trending topic information for diff --git a/lib/twitter/client/timeline.rb b/lib/twitter/client/timeline.rb index 9a4ebbd00..a90a8249d 100644 --- a/lib/twitter/client/timeline.rb +++ b/lib/twitter/client/timeline.rb @@ -8,7 +8,7 @@ module Timeline # @authenticated false # @rate_limited true # @param options [Hash] A customizable set of options. - # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object including only the status author's numerical ID when set to true, 't' or 1. + # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object with only the author's numerical ID 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/statuses/public_timeline @@ -19,10 +19,10 @@ def public_timeline(options={}) format.to_s.downcase == 'xml' ? response['statuses'] : response end - # Returns the 20 most recent statuses, including retweets if they exist, posted by the authenticating user and the user's they follow + # Returns the 20 most recent statuses, including retweets if they exist, posted by the authenticating user and the users they follow # # @note This method is identical to {Twitter::Client::Timeline#friends_timeline}, except that this method always includes retweets. - # @note This method is can only return up to 800 statuses, including retweets. + # @note This method can only return up to 800 statuses, including retweets. # @format :json, :xml # @authenticated true # @rate_limited true @@ -31,21 +31,21 @@ def public_timeline(options={}) # @option options [Integer] :max_id Returns results with an ID less than (that is, older than) or equal to the specified ID. # @option options [Integer] :count Specifies the number of records to retrieve. Must be less than or equal to 200. # @option options [Integer] :page Specifies the page of results to retrieve. - # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object including only the status author's numerical ID when set to true, 't' or 1. + # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object with only the author's numerical ID 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/statuses/home_timeline - # @example Return the 20 most recent statuses, including retweets if they exist, posted by the authenticating user and the user's they follow + # @example Return the 20 most recent statuses, including retweets if they exist, posted by the authenticating user and the users they follow # Twitter.home_timeline def home_timeline(options={}) response = get('statuses/home_timeline', options) format.to_s.downcase == 'xml' ? response['statuses'] : response end - # Returns the 20 most recent statuses posted by the authenticating user and the user's they follow + # Returns the 20 most recent statuses posted by the authenticating user and the users they follow # # @note This method is identical to {Twitter::Client::Timeline#home_timeline}, except that this method will only include retweets if the :include_rts option is set. - # @note This method is can only return up to 800 statuses. If the :include_rts option is set only 800 statuses, including retweets if they exist, can be returned. + # @note This method can only return up to 800 statuses. If the :include_rts option is set, only 800 statuses, including retweets if they exist, can be returned. # @format :json, :xml # @authenticated true # @rate_limited true @@ -54,12 +54,12 @@ def home_timeline(options={}) # @option options [Integer] :max_id Returns results with an ID less than (that is, older than) or equal to the specified ID. # @option options [Integer] :count Specifies the number of records to retrieve. Must be less than or equal to 200. # @option options [Integer] :page Specifies the page of results to retrieve. - # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object including only the status author's numerical ID when set to true, 't' or 1. + # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object with only the author's numerical ID when set to true, 't' or 1. # @option options [Boolean, String, Integer] :include_rts The timeline will contain native retweets (if they exist) in addition to the standard stream of tweets 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/statuses/friends_timeline - # @example Return the 20 most recent statuses, including retweets if they exist, posted by the authenticating user and the user's they follow + # @example Return the 20 most recent statuses, including retweets if they exist, posted by the authenticating user and the users they follow # Twitter.friends_timeline def friends_timeline(options={}) response = get('statuses/friends_timeline', options) @@ -69,9 +69,9 @@ def friends_timeline(options={}) # Returns the 20 most recent statuses posted by the specified user # # @todo Overload the method to allow fetching of the authenticated user's screen name from configuration. - # @note This method is can only return up to 3200 statuses. If the :include_rts option is set only 3200 statuses, including retweets if they exist, can be returned. + # @note This method can only return up to 3200 statuses. If the :include_rts option is set, only 3200 statuses, including retweets if they exist, can be returned. # @format :json, :xml - # @authenticated false unless the user you are trying to view the timeline of is protected + # @authenticated false unless the user whose timeline you're trying to view is protected # @rate_limited true # @param user [Integer, String] A Twitter user ID or screen name. # @param options [Hash] A customizable set of options. @@ -79,7 +79,7 @@ def friends_timeline(options={}) # @option options [Integer] :max_id Returns results with an ID less than (that is, older than) or equal to the specified ID. # @option options [Integer] :count Specifies the number of records to retrieve. Must be less than or equal to 200. # @option options [Integer] :page Specifies the page of results to retrieve. - # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object including only the status author's numerical ID when set to true, 't' or 1. + # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object with only the author's numerical ID when set to true, 't' or 1. # @option options [Boolean, String, Integer] :include_rts The timeline will contain native retweets (if they exist) in addition to the standard stream of tweets 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] @@ -92,9 +92,9 @@ def user_timeline(user, options={}) format.to_s.downcase == 'xml' ? response['statuses'] : response end - # Returns the 20 most recent mentions (status containing @username) for the authenticating user + # Returns the 20 most recent mentions (statuses containing @username) for the authenticating user # - # @note This method is can only return up to 800 statuses. If the :include_rts option is set only 800 statuses, including retweets if they exist, can be returned. + # @note This method can only return up to 800 statuses. If the :include_rts option is set, only 800 statuses, including retweets if they exist, can be returned. # @format :json, :xml # @authenticated true # @rate_limited true @@ -103,12 +103,12 @@ def user_timeline(user, options={}) # @option options [Integer] :max_id Returns results with an ID less than (that is, older than) or equal to the specified ID. # @option options [Integer] :count Specifies the number of records to retrieve. Must be less than or equal to 200. # @option options [Integer] :page Specifies the page of results to retrieve. - # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object including only the status author's numerical ID when set to true, 't' or 1. + # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object with only the author's numerical ID when set to true, 't' or 1. # @option options [Boolean, String, Integer] :include_rts The timeline will contain native retweets (if they exist) in addition to the standard stream of tweets 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/statuses/mentions - # @example Return the 20 most recent mentions (status containing @username) for the authenticating user + # @example Return the 20 most recent mentions (statuses containing @username) for the authenticating user # Twitter.mentions def mentions(options={}) response = get('statuses/mentions', options) @@ -125,7 +125,7 @@ def mentions(options={}) # @option options [Integer] :max_id Returns results with an ID less than (that is, older than) or equal to the specified ID. # @option options [Integer] :count Specifies the number of records to retrieve. Must be less than or equal to 200. # @option options [Integer] :page Specifies the page of results to retrieve. - # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object including only the status author's numerical ID when set to true, 't' or 1. + # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object with only the author's numerical ID 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/statuses/retweeted_by_me @@ -136,7 +136,7 @@ def retweeted_by_me(options={}) format.to_s.downcase == 'xml' ? response['statuses'] : response end - # Returns the 20 most recent retweets posted by users the authenticating user follow + # Returns the 20 most recent retweets posted by users followed by the authenticating user # # @format :json, :xml # @authenticated true @@ -146,11 +146,11 @@ def retweeted_by_me(options={}) # @option options [Integer] :max_id Returns results with an ID less than (that is, older than) or equal to the specified ID. # @option options [Integer] :count Specifies the number of records to retrieve. Must be less than or equal to 200. # @option options [Integer] :page Specifies the page of results to retrieve. - # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object including only the status author's numerical ID when set to true, 't' or 1. + # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object with only the author's numerical ID 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/statuses/retweeted_to_me - # @example Return the 20 most recent retweets posted by users the authenticating user follow + # @example Return the 20 most recent retweets posted by users followed by the authenticating user # Twitter.retweeted_to_me def retweeted_to_me(options={}) response = get('statuses/retweeted_to_me', options) @@ -167,7 +167,7 @@ def retweeted_to_me(options={}) # @option options [Integer] :max_id Returns results with an ID less than (that is, older than) or equal to the specified ID. # @option options [Integer] :count Specifies the number of records to retrieve. Must be less than or equal to 200. # @option options [Integer] :page Specifies the page of results to retrieve. - # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object including only the status author's numerical ID when set to true, 't' or 1. + # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object with only the author's numerical ID 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/statuses/retweets_of_me diff --git a/lib/twitter/client/tweets.rb b/lib/twitter/client/tweets.rb index 2132ffde0..3f9c7ce05 100644 --- a/lib/twitter/client/tweets.rb +++ b/lib/twitter/client/tweets.rb @@ -8,7 +8,7 @@ module Tweets # @rate_limited true # @param id [Integer] The numerical ID of the desired status. # @param options [Hash] A customizable set of options. - # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object including only the status author's numerical ID when set to true, 't' or 1. + # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object with only the author's numerical ID 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] The requested status. # @see http://dev.twitter.com/doc/get/statuses/show/:id @@ -21,18 +21,18 @@ def status(id, options={}) # Updates the authenticating user's status # - # @note A status update with text identical to the authenticating user's text identical to the authenticating user's current status will be ignored to prevent duplicates. + # @note A status update with text identical to the authenticating user's current status will be ignored to prevent duplicates. # @format :json, :xml # @authenticated true # @rate_limited false # @param status [String] The text of your status update, up to 140 characters. # @param options [Hash] A customizable set of options. # @option options [Integer] :in_reply_to_status_id The ID of an existing status that the update is in reply to. - # @option options [Float] :lat The latitude of the location this tweet refers to. This parameter 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 of the location this tweet refers to. The valid ranges for longitude is -180.0 to +180.0 (East is positive) inclusive. This parameter 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 [Float] :lat The latitude of the location this tweet refers to. 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 of the location this tweet refers to. 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] :place_id A place in the world. These IDs can be retrieved from {Twitter::Client::Geo#reverse_geocode}. # @option options [String] :display_coordinates Whether or not to put a pin on the exact coordinates a tweet has been sent from. - # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object including only the status author's numerical ID when set to true, 't' or 1. + # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object with only the author's numerical ID 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] The created status. # @see http://dev.twitter.com/doc/post/statuses/update @@ -43,7 +43,7 @@ def update(status, options={}) format.to_s.downcase == 'xml' ? response['status'] : response end - # Destroys the status specified by the ID parameter + # Destroys the specified status # # @note The authenticating user must be the author of the specified status. # @format :json, :xml @@ -51,7 +51,7 @@ def update(status, options={}) # @rate_limited false # @param id [Integer] The numerical ID of the desired status. # @param options [Hash] A customizable set of options. - # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object including only the status author's numerical ID when set to true, 't' or 1. + # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object with only the author's numerical ID 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] The deleted status. # @see http://dev.twitter.com/doc/post/statuses/destroy/:id @@ -70,7 +70,7 @@ def status_destroy(id, options={}) # @rate_limited false # @param id [Integer] The numerical ID of the desired status. # @param options [Hash] A customizable set of options. - # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object including only the status author's numerical ID when set to true, 't' or 1. + # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object with only the author's numerical ID 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] The original tweet with retweet details embedded. # @see http://dev.twitter.com/doc/post/statuses/retweet/:id @@ -89,7 +89,7 @@ def retweet(id, options={}) # @param id [Integer] The numerical ID of the desired status. # @param options [Hash] A customizable set of options. # @option options [Integer] :count Specifies the number of records to retrieve. Must be less than or equal to 100. - # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object including only the status author's numerical ID when set to true, 't' or 1. + # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object with only the author's numerical ID 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/statuses/retweets/:id @@ -109,7 +109,7 @@ def retweets(id, options={}) # @param options [Hash] A customizable set of options. # @option options [Integer] :count Specifies the number of records to retrieve. Must be less than or equal to 100. # @option options [Integer] :page Specifies the page of results to retrieve. - # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object including only the status author's numerical ID when set to true, 't' or 1. + # @option options [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object with only the author's numerical ID 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. # @option options [Boolean] :ids_only ('false') Only return user ids instead of full user objects. # @return [Array] diff --git a/lib/twitter/client/user.rb b/lib/twitter/client/user.rb index c7b81e02e..af48949cf 100644 --- a/lib/twitter/client/user.rb +++ b/lib/twitter/client/user.rb @@ -3,7 +3,7 @@ class Client module User # Returns extended information of a given user # - # @todo Overload the method to allow fetching of the authenticated screen name's from configuration. + # @todo Overload the method to allow fetching of the authenticated user's screen name from configuration. # @format :json, :xml # @authenticated false # @rate_limited true @@ -21,7 +21,7 @@ def user(user, options={}) format.to_s.downcase == 'xml' ? response['user'] : response end - # Return up to 100 users worth of extended information + # Returns extended information for up to 100 users # # @format :json, :xml # @authenticated true @@ -93,7 +93,7 @@ def suggestions(*args) # Access the profile image in various sizes for the user with the indicated screen name # - # @todo Overload the method to allow fetching of the authenticated screen name's from configuration. + # @todo Overload the method to allow fetching of the authenticated user's screen name from configuration. # @format :json, :xml # @authenticated false # @rate_limited false @@ -117,7 +117,7 @@ def profile_image(screen_name, 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] # @example Return the authenticated user's friends - # Twitter.freinds + # Twitter.friends # @overload friends(user, options={}) # @param user [Integer, String] A Twitter user ID or screen name. # @param options [Hash] A customizable set of options. @@ -129,7 +129,9 @@ def profile_image(screen_name, options={}) # Twitter.friends(7505382) # Same as above # @see http://dev.twitter.com/doc/get/statuses/friends # @format :json, :xml - # @authenticated false unless requesting it from a protected user; if getting this data of a protected user, you must auth (and be allowed to see that user). + # @authenticated false unless requesting it from a protected user + # + # If getting this data of a protected user, you must authenticate (and be allowed to see that user). # @rate_limited true def friends(*args) options = {:cursor => -1} @@ -152,7 +154,7 @@ def friends(*args) # @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 + # Twitter.followers # @overload followers(user, options={}) # @param user [Integer, String] A Twitter user ID or screen name. # @param options [Hash] A customizable set of options. @@ -164,7 +166,9 @@ def friends(*args) # Twitter.followers(7505382) # Same as above # @see http://dev.twitter.com/doc/get/statuses/followers # @format :json, :xml - # @authenticated false unless requesting it from a protected user; if getting this data of a protected user, you must auth (and be allowed to see that user). + # @authenticated false unless requesting it from a protected user + # + # If getting this data of a protected user, you must authenticate (and be allowed to see that user). # @rate_limited true def followers(*args) options = {:cursor => -1}