0
@@ -1,2 +1,3 @@
0
 .DS_Store
0
 /doc
0
+/coverage

0
@@ -19,6 +19,7 @@ Use that token in the next step:
0
 
0
 This is still alpha. It has been tested only with mocks, not live.
0
 Feel free to contribute; I plan to support more APIs (Microsoft, etc).
0
+Read more in Contacts::Gmail.
0
 
0
 Author: Mislav Marohnić (mislav.marohnic@gmail.com)
0
 
0
@@ -27,11 +28,18 @@ Author: Mislav Marohnić (mislav.marohnic@gmail.com)
0
 Contacts::Gmail.authentication_url
0
 - generates a URL for target with default parameters
0
 - should handle boolean parameters
0
+- skips parameters that have nil value
0
 
0
 Contacts::Gmail
0
-- is ready to query contacts from a specific account
0
+- should be set to query contacts from a specific account
0
 - fetches contacts feed via HTTP GET
0
 - handles gzipped response
0
 - raises a FetchingError when something goes awry
0
 - parses the resulting feed into name/email pairs
0
 - makes modification time available after parsing
0
+
0
+Contacts::Gmail GET query parameter handling
0
+- abstracts ugly parameters behind nicer ones
0
+- should have implicit :descending with :order
0
+- should have default :limit of 200
0
+- should skip nil values in parameters

0
@@ -6,15 +6,38 @@ require 'hpricot'
0
 require 'date'
0
 
0
 module Contacts
0
-  # AuthSub proxy authentication is used by web applications that need to
0
-  # authenticate their users to Google Accounts.
0
+  # Web applications should use
0
+  # AuthSub[http://code.google.com/apis/contacts/developers_guide_protocol.html#auth_sub]
0
+  # proxy authentication to get an authentication token for a Google account.
0
   # 
0
-  # http://code.google.com/apis/contacts/developers_guide_protocol.html#auth_sub
0
+  # First, get the user to follow the following URL:
0
+  # 
0
+  #   Contacts::Gmail.authentication_url('http://mysite.com/invite')
0
+  #
0
+  # After he authenticates successfully, Google will redirect him back to the target URL
0
+  # (specified as argument above) and provide the token GET parameter. Use it to create a
0
+  # new instance of this class and request the contact list:
0
+  #
0
+  #   gmail = Contacts::Gmail.new('example@gmail.com', params[:token])
0
+  #   contacts = gmail.contacts
0
+  #   #-> [ ['Fitzgerald', 'fubar@gmail.com', 'fubar@example.com'],
0
+  #         ['William Paginate', 'will.paginate@gmail.com'], ...
0
+  #         ]
0
   class Gmail
0
     DOMAIN     = 'www.google.com'
0
     AuthSubURL = "https://#{DOMAIN}/accounts/AuthSubRequest"
0
     AuthScope  = "http://#{DOMAIN}/m8/feeds/"
0
 
0
+    # URL to Google site where user authenticates. Afterwards, Google redirects to your
0
+    # site with the URL specified as +target+.
0
+    #
0
+    # Options are:
0
+    # * <tt>:scope</tt> -- the AuthSub scope in which the resulting token is valid
0
+    #   (default: "http://www.google.com/m8/feeds/")
0
+    # * <tt>:secure</tt> -- boolean indicating whether the token will be secure
0
+    #   (default: false)
0
+    # * <tt>:session</tt> -- boolean indicating if the token can be exchanged for a session token
0
+    #   (default: false)
0
     def self.authentication_url(target, options = {})
0
       params = { :next => target,
0
                  :scope => AuthScope,
0
@@ -40,6 +63,16 @@ module Contacts
0
 
0
     attr_reader :uri
0
     
0
+    # User email and token are required here. By default, an AuthSub token from Google is
0
+    # one-time only, which means you can only make a single request with it.
0
+    #
0
+    # ==== Options
0
+    # * <tt>:limit</tt> -- use a large number to fetch a bigger contact list (default: 200)
0
+    # * <tt>:offset</tt> -- 0-based value, can be used for pagination
0
+    # * <tt>:order</tt> -- currently the only value support by Google is "lastmodified"
0
+    # * <tt>:descending</tt> -- boolean
0
+    # * <tt>:updated_after</tt> -- string or time-like object, use to only fetch contacts
0
+    #   that were updated after this date
0
     def initialize(email, token, options = {})
0
       @token = token.to_s
0
       @email = email.to_s
0
@@ -112,14 +145,18 @@ module Contacts
0
       @updated_string = @doc.at('/feed/updated').inner_text
0
     end
0
 
0
+    # Timestamp of last update (DateTime). This value is available only after the XML
0
+    # document has been parsed; for instance after fetching the contact list.
0
     def updated_at
0
       @updated_at ||= DateTime.parse @updated_string if @updated_string
0
     end
0
 
0
+    # Timestamp of last update as it appeared in the XML document
0
     def updated_at_string
0
       @updated_string
0
     end
0
 
0
+    # Fetches, parses and returns the contact list.
0
     def contacts
0
       parse
0
       all = []