Copy-edit documentation

sferik · Nov 6, 2010 · 7873b03 · 7873b03
1 parent b05979d
commit 7873b03
Show file tree

Hide file tree

Showing 10 changed files with 91 additions and 83 deletions.
diff --git 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
 <tt>Twitter::Base</tt>, <tt>Twitter:Geo</tt>, <tt>Twitter::LocalTrends</tt>, and
 <tt>Twitter::Trends</tt> 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
@@ -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
@@ -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
@@ -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,21 +42,23 @@ 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
       #
       #   @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}