doc update: README and of getting session tokens

README.rdoc

@@ -1,44 +1,46 @@
-== Google Contacts API
+== Basic usage instructions
 
 Fetch users' contact lists from your web application without asking them to
 provide their passwords.
 
 First, register[http://code.google.com/apis/accounts/docs/RegistrationForWebAppsAuto.html]
 your application's domain. Then make users follow this URL:
 
-  Contacts::Gmail.authentication_url('http://mysite.com/invite')
+  Contacts::Google.authentication_url('http://mysite.com/invite')
 
 They will authenticate on Google and it will send them back to the URL
 provided. Google will add a token GET parameter to the query part of the URL.
 Use that token in the next step:
 
-  gmail = Contacts::Gmail.new('[email protected]', params[:token])
+  gmail = Contacts::Google.new('[email protected]', params[:token])
   contacts = gmail.contacts
   #-> [ ['Fitzgerald', '[email protected]', '[email protected]'],
         ['William Paginate', '[email protected]'], ...
         ]
 
-Read more in Contacts::Gmail. I plan to support more APIs (Microsoft, etc);
-feel free to contribute.
+Read more in Contacts::Google. I plan to support more APIs (Microsoft Live, for
+starters); feel free to contribute.
 
-Author: Mislav Marohnić ([email protected])
+Author: <b>Mislav Marohnić</b> ([email protected])
 
-== Specdoc
+== Documentation auto-generated from specifications
 
-Contacts::Gmail.authentication_url
+Contacts::Google.authentication_url
 - generates a URL for target with default parameters
 - should handle boolean parameters
 - skips parameters that have nil value
+- should be able to exchange one-time for session token
 
-Contacts::Gmail
-- should be set to query contacts from a specific account
+Contacts::Google
 - fetches contacts feed via HTTP GET
+- handles a normal response body
 - handles gzipped response
 - raises a FetchingError when something goes awry
 - parses the resulting feed into name/email pairs
+- parses a complex feed into name/email pairs
 - makes modification time available after parsing
 
-Contacts::Gmail GET query parameter handling
+Contacts::Google GET query parameter handling
 - abstracts ugly parameters behind nicer ones
 - should have implicit :descending with :order
 - should have default :limit of 200

Rakefile

@@ -40,7 +40,7 @@ end
 desc 'Generate RDoc documentation'
 Rake::RDocTask.new(:rdoc) do |rdoc|
   rdoc.rdoc_files.add ['README.rdoc', 'MIT-LICENSE', 'lib/**/*.rb']
-  rdoc.main = 'README.rdoc' # page to start on
+  rdoc.main = 'README.rdoc'
   rdoc.title = 'Google Contacts API'
 
   rdoc.rdoc_dir = 'doc'

lib/contacts/google.rb

@@ -10,6 +10,7 @@
 
 module Contacts
   # == Fetching Google Contacts
+  # 
   # Web applications should use
   # AuthSub[http://code.google.com/apis/contacts/developers_guide_protocol.html#auth_sub]
   # proxy authentication to get an authentication token for a Google account.
@@ -27,6 +28,22 @@ module Contacts
   #   #-> [ ['Fitzgerald', '[email protected]', '[email protected]'],
   #         ['William Paginate', '[email protected]'], ...
   #         ]
+  #
+  # == Storing a session token
+  #
+  # The basic token that you will get after the user has authenticated on Google is valid
+  # for only one request. However, you can specify that you want a session token which
+  # doesn't expire:
+  # 
+  #   Contacts::Google.authentication_url('http://mysite.com/invite', :session => true)
+  #
+  # When the user authenticates, he will be redirected back with a token which still isn't
+  # a session token, but can be exchanged for one!
+  #
+  #   token = Contacts::Google.sesion_token(params[:token])
+  #
+  # Now you have a permanent token. Store it with other user data so you can query the API
+  # on his behalf without him having to authenticate on Google each time.
   class Google
     DOMAIN      = 'www.google.com'
     AuthSubPath = '/accounts/AuthSub' # all variants go over HTTPS
@@ -89,7 +106,7 @@ def initialize(user_id, token)
       @base_path = "/m8/feeds/contacts/#{CGI.escape(@user)}/base"
     end
 
-    def get(params)
+    def get(params) #:nodoc:
       response = Net::HTTP.start(DOMAIN) do |google|
         google.get(@base_path + '?' + query_string(params), @headers)
       end