Skip to content

Commit

Permalink
Copy-edit documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@dianakimball @sferik
dianakimball authored and sferik committed Nov 6, 2010
1 parent b05979d commit 7873b03
Show file tree
Hide file tree
Showing 10 changed files with 91 additions and 83 deletions.
20 changes: 12 additions & 8 deletions README.mkd
View file
Expand Up @@ -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
Expand Down Expand Up @@ -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"}
Expand All @@ -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)
Expand All @@ -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)
Expand All @@ -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)"
---------------------------------------------------------------------------------------------------------------------------
Expand Down Expand Up @@ -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
-------------------
Expand All @@ -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.
8 changes: 5 additions & 3 deletions lib/twitter/client/account.rb
View file
Expand Up @@ -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]
Expand All @@ -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)
Expand Down Expand Up @@ -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.
Expand Down
6 changes: 3 additions & 3 deletions lib/twitter/client/favorites.rb
View file
Expand Up @@ -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.
Expand All @@ -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
Expand All @@ -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
Expand Down
22 changes: 13 additions & 9 deletions lib/twitter/client/friends_and_followers.rb
View file
Expand Up @@ -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}
Expand All @@ -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}
Expand Down

0 comments on commit 7873b03

Please sign in to comment.