README.rdoc in github_api-0.2.0 vs README.rdoc in github_api-0.2.1

@@ -10,32 +10,24 @@
 
   gem install github_api
 
 or in your Gemfile
 
-  gem "github_api", "~> 0.2.0"
+  gem "github_api", "~> 0.2.1"
 
 == Usage
 
 Create a new client instance
 
   @github = Github.new
 
-At this stage you can also supply various configuration parameters, such as :user, :repo, :org, :oauth_token, :login, :password or :basic_auth
-which are used thoughtout the API
+At this stage you can also supply various configuration parameters, such as :user, :repo, :org, :oauth_token, :login, :password or :basic_auth which are used thoughtout the API
 
   @github = Github.new :user => 'peter-murach', :repo => 'github-api'
 
-In order to authenticate the user through OAuth2 on GitHub you need to
+You can authenticate either using OAuth authentication convenience methods(see section OAuth) or through basic authentication by passing your login and password credentials
 
-* visit https://github.com/account/applications/ and register your app
-* authorize your credentials https://github.com/login/oauth/authorize
-* get your token https://github.com/login/oauth/access_token
-
-Once you have your consumer and token keys, configure your github instance following instructions under Configuration.
-
-You can also use basic authentication by passing your login and password credentials
   @github = Github.new :login => 'peter-murach', :password => '...'
 
   or use convenience method:
 
   @github = Github.new :basic_auth => 'login:password'
@@ -83,11 +75,11 @@
 
 All method calls form ruby like sentences and allow for intuitive api navigation, for instance
 
   @github = Github.new :oauth_token => '...'
   @github.users.following 'wycats'  # => returns users that 'wycats' is following
-  @github.users.following? 'wycats' # => returns true if following, otherwise false
+  @github.users.following 'wycats' # => returns true if following, otherwise false
 
 For specification on all available methods go to http://developer.github.com/v3/ or
 read the rdoc, all methods are documented there with examples of usage.
 
 == Inputs
@@ -104,19 +96,40 @@
 
   @github.git_data.tree 'peter-murach', 'github', 'c18647b75d72f19c1e0cc8af031e5d833b7f12ea', :recursive => true do |file|
     puts file.path
   end
 
+== OAuth
+
+In order to authenticate the user through OAuth2 on GitHub you need to
+
+* visit https://github.com/account/applications/ and register your app
+
+* authorize your credentials https://github.com/login/oauth/authorize
+  You can use convenience methods to help you achieve this that come with this gem:
+
+    @github = Github.new :client_id => '...', :client_secret => '...'
+    @github.authorize_url :redirect_uri => 'http://localhost', :scope => 'repo'
+    # => "https://github.com/login/oauth/authorize?scope=repo&response_type=code&client_id='...'&redirect_uri=http%3A%2F%2Flocalhost"
+
+    After you get your authorization code, call to receive your access_token
+
+    token = github.get_token( authorization_code )
+
+Once you have your access token, configure your github instance following instructions under Configuration.
+
 == MIME Types
 
-Provides support for the following mime types
+Issues, PullRequests and few other API leverage custom mime types which are <tt>:json</tt>, <tt>:blob</tt>, <tt>:raw</tt>, <tt>:text</tt>, <tt>:html</tt>, <tt>:full</tt>. By default <tt>:raw</tt> is used.
 
 In order to pass a mime type with your request do
 
-  @github = Github.new :oauth_token
-  @github...
+  @github = Github.new
+  @github.pull_requests.pull_requests 'peter-murach', 'github', :mime_type => :full
 
+  Your header will contain 'Accept: "application/vnd.github-pull.full+json"' which in turn returns raw, text and html representations in response body.
+
 == Configuration
 
 Certain methods require authentication. To get your GitHub OAuth v2 credentials,
 register an app at https://github.com/account/applications/
 
@@ -130,10 +143,16 @@
   Github.new(:oauth_token => YOUR_OAUTH_TOKEN)
   Github.new(:basic_auth => 'login:password)
 
 All parameters can be overwirtten as per method call. By passing parameters hash...
 
+== Caching
+
+Each <tt>get</tt> request by default is not going to be cached. In order to set the cache do... If no cache type is provided a default memoization is done.
+
+  Github.cache do...
+
 == Examples
 
 Some api methods require input parameters, these are added simply as a hash properties, for instance
 
   @issues = Github::Issues.new :user => 'peter-murach', :repo => 'github-api'
@@ -154,20 +173,32 @@
 Query requests instead of http responses return boolean values
 
   @github = Github.new
   @github.orgs.public_member? 'github', 'technoweenie' # => true
 
-== Caching
+== Rails Example
 
-Each call by default is not going to be cached. In order to set the inmemory cache do...
+A Rails controller that allows a user to authorize their GitHub account and then perform request.
 
+  class GithubController < ApplicationController
+
+    def authorize
+      github = Github.new :client_id => '...', :client_secret => '...'
+      address = github.authorize_url :redirect_uri => 'http://...', :scope => 'repo'
+      redirect_to address
+    end
+
+    def callback
+      authorization_code = params[:code]
+      token = github.get_token authorization_code
+      access_token = token.token
+    end
+  end
+
 == TODO
 
-* Add support for mime types
 * Add request caching - local filestore?, http caching?.
-* Add oauth2 helper methods.
 * Add response processing methods
-* Add helper methods to return iterators over most common collections.
 * Add response set helper methods e.i. pagination.
 * Add DSL falvoured api access
 
 == Contributing to github