Additional documentation.

.gitignore

@@ -3,4 +3,5 @@ pkg
 Gemfile.lock
 .rvmrc
 *.rbc
-*~
+*~
+.yardoc/

lib/koala/http_service.rb

@@ -64,76 +64,92 @@ def self.encode_params(param_hash)
     # deprecations
     # not elegant or compact code, but temporary
 
+    # @private
     def self.always_use_ssl
       Koala::Utils.deprecate("HTTPService.always_use_ssl is now HTTPService.http_options[:use_ssl]; always_use_ssl will be removed in a future version.")
       http_options[:use_ssl]
     end
 
+    # @private
     def self.always_use_ssl=(value)
       Koala::Utils.deprecate("HTTPService.always_use_ssl is now HTTPService.http_options[:use_ssl]; always_use_ssl will be removed in a future version.")
       http_options[:use_ssl] = value
     end
 
+    # @private
     def self.timeout
       Koala::Utils.deprecate("HTTPService.timeout is now HTTPService.http_options[:timeout]; .timeout will be removed in a future version.")
       http_options[:timeout]
     end
 
+    # @private
     def self.timeout=(value)
       Koala::Utils.deprecate("HTTPService.timeout is now HTTPService.http_options[:timeout]; .timeout will be removed in a future version.")
       http_options[:timeout] = value
     end
 
+    # @private
     def self.timeout
       Koala::Utils.deprecate("HTTPService.timeout is now HTTPService.http_options[:timeout]; .timeout will be removed in a future version.")
       http_options[:timeout]
     end
 
+    # @private
     def self.timeout=(value)
       Koala::Utils.deprecate("HTTPService.timeout is now HTTPService.http_options[:timeout]; .timeout will be removed in a future version.")
       http_options[:timeout] = value
     end
 
+    # @private
     def self.proxy
       Koala::Utils.deprecate("HTTPService.proxy is now HTTPService.http_options[:proxy]; .proxy will be removed in a future version.")
       http_options[:proxy]
     end
 
+    # @private
     def self.proxy=(value)
       Koala::Utils.deprecate("HTTPService.proxy is now HTTPService.http_options[:proxy]; .proxy will be removed in a future version.")
       http_options[:proxy] = value
     end
 
+    # @private
     def self.ca_path
       Koala::Utils.deprecate("HTTPService.ca_path is now (HTTPService.http_options[:ssl] ||= {})[:ca_path]; .ca_path will be removed in a future version.")
       (http_options[:ssl] || {})[:ca_path]
     end
 
+    # @private
     def self.ca_path=(value)
       Koala::Utils.deprecate("HTTPService.ca_path is now (HTTPService.http_options[:ssl] ||= {})[:ca_path]; .ca_path will be removed in a future version.")
       (http_options[:ssl] ||= {})[:ca_path] = value
     end
 
+    # @private
     def self.ca_file
       Koala::Utils.deprecate("HTTPService.ca_file is now (HTTPService.http_options[:ssl] ||= {})[:ca_file]; .ca_file will be removed in a future version.")
       (http_options[:ssl] || {})[:ca_file]
     end
 
+    # @private
     def self.ca_file=(value)
       Koala::Utils.deprecate("HTTPService.ca_file is now (HTTPService.http_options[:ssl] ||= {})[:ca_file]; .ca_file will be removed in a future version.")
       (http_options[:ssl] ||= {})[:ca_file] = value
     end
 
+    # @private
     def self.verify_mode
       Koala::Utils.deprecate("HTTPService.verify_mode is now (HTTPService.http_options[:ssl] ||= {})[:verify_mode]; .verify_mode will be removed in a future version.")
       (http_options[:ssl] || {})[:verify_mode]
     end
 
+    # @private
     def self.verify_mode=(value)
       Koala::Utils.deprecate("HTTPService.verify_mode is now (HTTPService.http_options[:ssl] ||= {})[:verify_mode]; .verify_mode will be removed in a future version.")
       (http_options[:ssl] ||= {})[:verify_mode] = value
     end
 
+    private 
+
     def self.process_options(options)
       if typhoeus_options = options.delete(:typhoeus_options)
         Koala::Utils.deprecate("typhoeus_options should now be included directly in the http_options hash.  Support for this key will be removed in a future version.")
@@ -159,6 +175,7 @@ def self.process_options(options)
     end   
   end
 
+  # @private
   module TyphoeusService
     def self.deprecated_interface
       # support old-style interface with a warning
@@ -167,6 +184,7 @@ def self.deprecated_interface
     end
   end
 
+  # @private
   module NetHTTPService
     def self.deprecated_interface
       # support old-style interface with a warning

lib/koala/oauth.rb

@@ -23,7 +23,7 @@ def initialize(app_id, app_secret, oauth_callback_url = nil)
 
       # Parses the cookie set Facebook's JavaScript SDK.
       #
-      # @note to parse Facebook's new signed cookie format, this method makes a request to Facebook each time.
+      # @note in parsing Facebook's new signed cookie format this method has to make a request to Facebook.
       #       We recommend storing authenticated user info in your Rails session (or equivalent) and only
       #       calling this when needed.
       #
@@ -92,7 +92,7 @@ def url_for_oauth_code(options = {})
       # 
       # @note (see #url_for_oauth_code)
       #
-      # @param code the OAuth code received from Facebook
+      # @param code an OAuth code received from Facebook
       # @param options any additional query parameters to add to the URL
       #
       # @raise (see #url_for_oauth_code)
@@ -125,12 +125,32 @@ def url_for_dialog(dialog_type, options = {})
 
       # access tokens
 
+      # Fetches an access token, token expiration, and other info from Facebook.
+      # Useful when you've received an OAuth code using the server-side authentication process.
+      # @see url_for_oauth_code
+      # 
+      # @param code (see #url_for_access_token)
+      # @param options any additional parameters to send to Facebook when redeeming the token
+      # 
+      # @raise Koala::Facebook::APIError if Facebook returns an error response 
+      # 
+      # @return a hash of the access token info returned by Facebook (token, expiration, etc.) 
       def get_access_token_info(code, options = {})
         # convenience method to get a parsed token from Facebook for a given code
         # should this require an OAuth callback URL?
         get_token_from_server({:code => code, :redirect_uri => options[:redirect_uri] || @oauth_callback_url}, false, options)
       end
 
+
+      # Fetches the access token (ignoring expiration and other info) from Facebook.
+      # Useful when you've received an OAuth code using the server-side authentication process.
+      # @see get_access_token_info
+      # 
+      # @param (see #get_access_token_info)
+      #
+      # @raise (see #get_access_token_info)
+      #
+      # @return the access token provided by Facebook
       def get_access_token(code, options = {})
         # upstream methods will throw errors if needed
         if info = get_access_token_info(code, options)